| name | potpie-cli |
| version | 2 |
| description | Use when the task is centered on running, explaining, configuring, or troubleshooting the `potpie` command: doctor, login, pot management, source registration, search, graph workbench reads/writes, and pot scope behavior. |
Potpie CLI
Use this skill when the user is asking about the potpie command itself. For
ordinary project-memory context, prefer the relevant use-case skill first.
Setup And Scope
For repo-local CLI install/reinstall from this checkout, use:
make cli-install
make cli-status
potpie doctor
Do not use raw uv tool install --editable … or pip install for day-to-day
local reinstalls. Reserve uv tool install potpie / pip install potpie for
the published package.
potpie doctor
potpie --json doctor
make cli-status
uv tool list
which -a potpie
potpie login <api-key> --url <host>
potpie pot list
potpie pot use <pot-id-or-alias>
potpie --json pot info
potpie pot linked --repo current
potpie pot default set --repo current <pot-id-or-alias>
potpie --json source list
potpie source add repo .
potpie source add repo <owner/repo> --pot <pot>
Pot scope resolves in this order:
- Explicit
--pot.
- Repo-local default set by
source add repo or pot default set.
- Registered repo source matching the current working tree path or
remote.origin.url.
- Active pot from
potpie pot use.
- Clear failure asking for setup, source registration, default selection, or
explicit
--pot.
A pot is a project boundary and may span multiple repos. Do not automatically
narrow timeline reads to the current repo.
source add repo sets the repo-local default by default. Use --no-default
only when deliberately registering a repo to a non-default pot. If graph output
warns that the selected pot is empty but another linked pot has claims, run the
suggested pot default set --repo current <pot> command before continuing.
Search
potpie search "query"
potpie --json search "query"
potpie search "query" --include decisions,features
potpie search "query" --pot <pot-id-or-alias>
Graph Workbench
potpie --json graph status
potpie --json graph catalog --task "<task>"
potpie --json graph describe <subgraph> --view <view> --examples
potpie graph read --subgraph <subgraph> --view <view> --limit 20
potpie graph search-entities "<name>" --type Service --limit 10
potpie --json graph propose --file mutation.json
potpie --json graph commit <plan_id> --verify
potpie --json graph history --plan <plan_id>
potpie --json graph quality summary
Use potpie-graph for advanced graph workbench details.
Boundaries
Repository links, docs, tickets, PRs, and logs are interpreted by the harness and
written with graph workbench mutations. Do not use pot-level connector queueing or
deterministic local code scans as the agent ingestion path.
Do not use scanner-driven graph updates.
For CLI failures, stay in this skill: run potpie doctor, make cli-status, or
uv tool list for install facts. For repo-local reinstall use make cli-install
(not raw uv tool install). Do not use python -m pip show potpie-context-engine for local uv-tool installs. Inspect JSON output when
useful, check API URL/key config, confirm pot scope, and verify source
registration before changing project code.
