// Use when the task involves running, explaining, or troubleshooting the Potpie CLI. Covers doctor, login, pot management, search, and ingest commands.
Use when an agent needs project context from the context engine through MCP tools. Covers context_resolve recipes for feature, debugging, review, operations, docs, and onboarding without adding separate context tools.
Use when the Potpie CLI is failing — especially around API key, URL config, 401, 404, pot scope, or search/ingest HTTP errors.
Use when the task is about pot resolution: pot use, env maps, git origin parsing, repo-to-pot mapping, or search/ingest scope inference.
| name | potpie-cli |
| description | Use when the task involves running, explaining, or troubleshooting the Potpie CLI. Covers doctor, login, pot management, search, and ingest commands. |
Use this skill when the task is centered on the potpie command.
# Setup and auth
potpie login <api-key> --url http://your-potpie-host
potpie doctor
# Pot management
potpie pot pots # list all pots
potpie pot use <uuid-or-alias> # set active pot
potpie pot alias <name> <uuid> # create local alias
potpie pot list # show env maps + active pot
# Search
potpie search "your query"
potpie search "query" -n 15
potpie search "query" --node-labels PullRequest,Decision
potpie search "query" --with-temporal
# Ingest
potpie ingest "Your note here"
potpie ingest --name "Title" --episode-body "Body" --source "meeting"
potpie ingest "Note" --sync
potpie ingest --file notes.txt
# Machine-readable output
potpie --json doctor
potpie --json search "query"
potpie --json ingest "note"
potpie login <key> --url <host> — save credentials.potpie doctor — verify health + auth.potpie pot pots — list available pots.potpie pot use <id> — set active pot.For search and ingest, the pot is chosen in this order:
pot use.CONTEXT_ENGINE_REPO_TO_POT env map matched on owner/repo.CONTEXT_ENGINE_POTS env map (inverse lookup).origin remote parsed from --cwd.--json — machine-readable JSON on stdout (global, before subcommand).--verbose / -v — full tracebacks on errors.--source — default source label for ingest (global) or search filter.--sync — synchronous ingest (wait for apply, not just queue).--cwd — git working tree for pot inference.| Symptom | Fix |
|---|---|
Potpie API not configured | Set POTPIE_API_URL + POTPIE_API_KEY, or run potpie login. |
401 Invalid API key | Key is wrong or expired. Re-run potpie login. |
Pot scope required | Run potpie pot use <id> or pass a pot UUID explicitly. |
GET /health fails | Wrong base URL, wrong port, or server is down. |
409 duplicate_ingest | Same idempotency key already ingested. Safe to ignore or use --idempotency-key. |