Potpie CLI
Apps & Automationpotpie-cliPotpie CLI is an Agent Skill for apps & automation published in the potpie-ai/potpie repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/potpie-ai/potpie/blob/HEAD/potpie/context-engine/adapters/inbound/cli/templates/agent_bundle/.agents/skills/potpie-cli/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/potpie-cli, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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
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 repoorpot 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. 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.