Skip to main content
These commands are the smallest stable user-facing surface for interacting with Potpie’s context engine.

​
Command Family

CommandPurpose
potpie resolvePull a bounded context package for a task.
potpie searchRun a narrow follow-up lookup against known entities or phrases.
potpie recordPersist a durable project learning back into the graph.
Internally, these are treated as the core context contract. New use cases tend to become new option values rather than brand-new top-level commands.

​
potpie resolve

potpie resolve [OPTIONS] TASK
Pulls the context an agent or developer should read before starting work.

​
Arguments

ArgumentTypeDescription
taskstrThe task to pull context for. Required.

​
Options

OptionTypeDescription
--intentstrWork intent. Defaults to feature.
--includestrComma-separated include families to constrain the returned context.
--modestrRetrieval mode: fast, balanced, verify, or deep.
--potstrPot to resolve against.

​
Examples

potpie resolve "what should I know before working in this repository?"
potpie resolve "trace the authentication flow" --intent debug --mode deep
potpie resolve "prepare for a refactor of billing webhooks" --include code,history,decisions

potpie search [OPTIONS] QUERY
Use this when you already know the rough phrase, entity, workflow, bug, or convention you need to narrow down.

​
Arguments

ArgumentTypeDescription
querystrPhrase or entity to look up. Required.

​
Options

OptionTypeDescription
--includestrInclude-family filter.
--potstrPot to search.

​
Examples

potpie search "authentication flow"
potpie search "deploy rollback runbook"
potpie search "rate limiter middleware" --include code,docs

​
potpie record

potpie record [OPTIONS]
Writes a durable project learning back into the context system.

​
Options

OptionTypeDescription
--typestrRecord type such as fix, decision, or preference. Required.
--summarystrThe durable learning to persist. Required.
--scopestrScope in key:value form, for example service:inventory-svc.
--potstrPot to write into.

​
Examples

potpie record --type decision --summary "Prefer the context-engine CLI for graph work"
potpie record --type fix --summary "Invoice retries depend on Stripe webhook idempotency" --scope service:billing
potpie record --type preference --summary "Use feature flags for staged rollouts" --scope team:platform

​
When To Use Which

NeedCommand
”I am about to work on X. Give me the bounded context.”resolve
”I know the name or phrase. Narrow it down.”search
”This is important enough to keep in the project memory.”record

​
Typical Flow

potpie resolve "debug intermittent webhook failures" --intent debug --mode verify
potpie search "stripe retry handler"
potpie record --type fix --summary "Webhook retries fan into the async retry worker" --scope service:payments