CLI Commands
The potpie CLI is the primary interface for both humans and AI agents. All commands operate within the context of the active pot (workspace). Every command supports --json for machine-readable output.
Setup & Authentication
Potpie Account
| Command |
Description |
potpie setup |
Run first-time local setup for config, daemon, default pot, and agent skills |
potpie login |
Sign in to Potpie (browser session or --api-key for key auth) |
potpie logout |
Remove Potpie account auth from local credential files |
potpie whoami |
Show current authenticated identity |
potpie setup --repo . --agent claude
potpie login
potpie login --api-key sk-... --url http://127.0.0.1:8001
Integration Logins
Connect external services so Potpie can index repos, issues, and docs.
Status & Diagnostics
| Command |
Description |
potpie status |
Show integration auth status |
potpie status --verify |
Verify integration credentials with API checks |
potpie status --host |
Check daemon, pot, graph, and skill readiness |
potpie doctor |
Run local diagnostics for daemon, backend, and skill drift |
potpie status --host
potpie doctor
Pot Management
A pot is a workspace/tenant boundary. Every query, source, and graph operation is scoped to one pot.
| Command |
Description |
potpie pot list |
List all pots (--local, --managed, or --all) |
potpie pot info |
Show details of the active pot |
potpie pot create <name> |
Create a new pot (optionally --repo . and --use) |
potpie pot use <id-or-name> |
Switch to a different pot |
potpie use <id-or-name> |
Shorthand for pot use (supports --local / --managed) |
potpie pot rename <id> <new> |
Rename a pot |
potpie pot reset |
Reset a pot's graph state (--confirm required) |
potpie pot archive <id> |
Archive a pot |
potpie pot list
potpie pot create my-project --repo . --use
potpie use my-project
Source Management
| Command |
Description |
potpie source add repo <path> |
Register a repo as a source for the active pot |
potpie source list |
List registered sources |
potpie source status |
Show source registration status |
potpie source remove <id> |
Remove a registered source |
potpie source add repo .
potpie source list --json
Note
source add repo only records source metadata for pot resolution. It does not scan or ingest the repository — ingestion happens through agent-led semantic writes.
Integration Browsing
After logging in to an integration, you can browse its data directly from the CLI.
Context Operations
| Command |
Description |
potpie resolve "<task>" |
Pull context an agent should read before doing a task |
potpie search "<query>" |
Look up a file, workflow, bug, decision, or convention |
potpie record --type <type> --summary "<text>" |
Write a durable project learning |
potpie resolve "what should I know before working in this repository?"
potpie search "authentication flow"
potpie record --type decision --summary "Prefer the context-engine CLI for graph work"
Graph Workbench
The graph workbench provides direct, lower-level access to the context graph.
Discovery & Reads
| Command |
Description |
potpie graph status |
Aggregate readiness: pot, graph, backend, ledger, skills |
potpie graph catalog |
Discover available subgraphs, views, and mutation policies |
potpie graph describe <subgraph> |
Describe a subgraph's views, schemas, and examples |
potpie graph search-entities |
Search entities by query, subgraph, name, or external ID |
potpie graph read |
Read bounded graph views with provenance and version metadata |
potpie graph history --entity <id> |
View audit history for an entity |
potpie graph neighborhood |
Explore entity relationships and connected subgraphs |
potpie graph inspect |
Inspect raw graph data for debugging |
potpie graph status --json
potpie graph catalog --task "debug refund failures"
potpie graph search-entities --query "bulk refunds" --subgraph features
potpie graph read --subgraph debugging --view prior_occurrences --scope service:refunds-api
Writes & Proposals
| Command |
Description |
potpie graph propose --file mutation.json |
Create an inspectable semantic mutation plan (no graph write) |
potpie graph commit <plan-id> |
Apply a validated plan and write audit/history |
potpie graph mutate |
Direct semantic graph mutation |
potpie graph mutation-template |
Generate a mutation template for a given subgraph |
potpie graph nudge |
Trigger a graph nudge event |
potpie graph propose --file mutation.json
potpie graph commit mutation-plan:01JY8T5C
Inbox
Pending graph work that hasn't been committed yet.
| Command |
Description |
potpie graph inbox add |
Capture pending graph work with summary and evidence |
potpie graph inbox list |
List pending inbox items |
potpie graph inbox show <id> |
Show details of an inbox item |
potpie graph inbox claim <id> |
Claim an inbox item for processing |
potpie graph inbox mark-applied <id> |
Mark an item as applied |
potpie graph inbox mark-rejected <id> |
Mark an item as rejected |
potpie graph inbox close <id> |
Close an inbox item |
Quality
Read-only graph quality reports.
| Command |
Description |
potpie graph quality summary |
Overall graph quality report |
potpie graph quality duplicate-candidates |
Find potential duplicate entities |
potpie graph quality stale-facts |
Identify stale or outdated claims |
potpie graph quality conflicting-claims |
Find conflicting claims |
potpie graph quality orphan-entities |
Find entities with no relationships |
potpie graph quality low-confidence |
Find low-confidence claims |
potpie graph quality projection-drift |
Check for drift between projections and claims |
Bulk Operations
| Command |
Description |
potpie graph bulk apply |
Chunked semantic graph mutation application |
Admin
| Command |
Description |
potpie graph export <file> |
Export graph data |
potpie graph import <file> |
Import graph data into a pot |
potpie graph repair |
Repair graph indexes (--semantic-index, --all) |
Timeline
| Command |
Description |
potpie timeline recent |
Project-wide event view, deduped and sorted by time |
potpie timeline recent --time-window 7d --service refunds-api
Backend
| Command |
Description |
potpie backend list |
List available graph backend profiles |
potpie backend status |
Show active backend health and capabilities |
potpie backend use <profile> |
Switch graph backend profile (e.g. embedded) |
potpie backend doctor |
Run backend-specific diagnostics |
Cloud Sync
| Command |
Description |
potpie cloud push |
Push a local pot snapshot to the managed backend |
potpie cloud pull |
Pull a managed pot snapshot to local |
Warning
Cloud push/pull moves a pot snapshot between local and managed backends. This is always explicit — registering a source or using a managed ledger does not trigger cloud sync.
Daemon
Local daemon administration (recovery tools, not onboarding steps).
| Command |
Description |
potpie daemon status |
Show daemon process status |
potpie daemon logs |
View daemon logs (--follow for live) |
potpie daemon restart |
Restart the local daemon |
potpie daemon stop |
Stop the local daemon |
Skills
| Command |
Description |
potpie skills list |
List available skills |
potpie skills install --agent <agent> |
Install skills for a harness (--scope global\|project) |
potpie skills update --agent <agent> |
Update installed skills |
potpie skills remove --agent <agent> |
Remove installed skills |
potpie skills status --agent <agent> |
Check skill installation status and drift |
potpie skills add <path-or-url> |
Add a custom skill |
potpie skills install --agent cursor
potpie skills status --agent claude --json
UI
| Command |
Description |
potpie ui |
Open the local graph explorer served by the daemon |
Config
| Command |
Description |
potpie config get <key> |
Read a config value |
potpie config set <key> <value> |
Write a config value |
potpie config set cloud.backend_url https://potpie.example.com
Exit codes
| Code |
Meaning |
0 |
Success |
1 |
Command or validation failure |
2 |
Daemon/API/dependency unavailable |
3 |
Partial/degraded result |
4 |
Auth/permission failure |