Skip to main content
Potpie is a CLI-first product. The command surface is not a thin wrapper around HTTP endpoints — it is the primary interface for local setup, source registration, context retrieval, graph reads, and operational control. Both humans and AI agent harnesses (Claude Code, Cursor, OpenAI Codex, OpenCode) use the same CLI.
New to Potpie? Start with Introduction and Installation before diving into the reference.

​
Command Families

CLI Manual

Complete man-page style reference. All commands, options, exit codes, environment variables, and file paths in one place.

Setup & Lifecycle

Install Potpie, run first-time setup, verify readiness, inspect local state, and launch the UI.

Context Commands

Pull context for a task, run narrow follow-up searches, and record durable project learnings.

Integrations & Auth

Sign into Potpie, connect GitHub, Linear, Jira, and Confluence, and inspect integration status.

Pots & Sources

Manage workspace boundaries, repo-local defaults, source registration, and ingestion entry points.

Graph & Operations

Daemon lifecycle, services, event ledger, graph workbench, timeline reads, backend profiles, and skills.

​
Root Command

potpie [OPTIONS] COMMAND [ARGS]...

​
Global Options

OptionDescription
--jsonEmit machine-readable JSON. Useful for piping to jq or consuming from agent harnesses.
--verbose, -vShow verbose tracebacks on errors.
--versionPrint potpie-context-engine version, Python version, and executable path.
--helpShow root help. Available on every subcommand.

​
Command Index

FamilyCommands
Contextresolve, search, record
Setup & readinesssetup, status, doctor, whoami, ui, config
Auth & integrationslogin, logout, github, linear, jira, confluence, auth
Workspace routinguse, pot, source
Runtime operationsdaemon, service, ledger, graph, timeline, backend, skills, cloud
# Install
uv tool install potpie

# Set up local environment (interactive wizard on TTY)
potpie setup --repo . --agent claude

# Verify readiness
potpie status --host

# Connect GitHub
potpie github login

# Register the repository as a source
potpie source add repo .

# Resolve context to confirm everything is working
potpie resolve "what should I know before working in this repository?"

# Open the graph explorer
potpie ui

​
Important Model

  • source add registers metadata only. It does not ingest or scan the repository by itself. Context is pulled on demand by resolve, search, agents, or graph reads.
  • External-system sync runs through pot-attached connector commands such as pot linear-team diff-sync and pot jira-project diff-sync.
  • The graph workbench lives under potpie graph. It is a CLI command group, not an HTTP API.
  • All commands default to the active pot. Use --pot <name> to scope a single command without changing the active pot.
  • Local and managed pots use the same CLI surface. After potpie login, managed pots appear in potpie pot list and potpie use.

​
Output Contract

FormatHow to get it
Human (default)Action-oriented summary with a recommended next command
JSONPass --json to any command
Exit codes:
CodeMeaning
0Success
1General error
2Usage or argument validation error
3Degraded — setup completed but one or more hard steps failed
4Authentication error
5Service unavailable