Skip to main content
This page covers the commands you use to install, bootstrap, inspect, and operate a local Potpie environment.

​
potpie setup

potpie setup [OPTIONS]
Idempotent first-run provisioning for config, storage, daemon, default pot, and skills.

​
Options

OptionTypeDescription
--repostrRepository path to bind during setup. Defaults to ..
--potstrDefault pot name to create or use. Defaults to default.
--agentstrHarness/agent profile to configure. Defaults to claude.
--backendstrGraph backend profile for this setup run.
--scanboolEnable scanning during setup when supported.
--dry-runboolPreview setup steps without executing them.
--yes, -yboolAssume yes for prompts.
--daemon / --in-processboolChoose detached daemon mode or in-process mode.

​
Examples

potpie setup
potpie setup --repo . --agent claude
potpie setup --repo . --agent codex --backend falkordb
potpie setup --dry-run

​
potpie status

potpie status [OPTIONS]
By default this shows integration auth status. Use --host for daemon, pot, backend, and skills readiness.

​
Options

OptionTypeDescription
--verifyboolVerify integration credentials with lightweight API checks.
--hostboolSwitch from auth status to host/pot readiness.
--intentstrHost-status intent, default feature.
--harnessstrHarness used for host-status checks, default claude.
--potstrPot to evaluate for host status.

​
Examples

potpie status
potpie status --verify
potpie status --host
potpie status --host --pot default --intent feature --harness claude

​
potpie doctor

potpie doctor
Runs local diagnostics across:
  • daemon mode and uptime
  • backend readiness and implemented capabilities
  • active pot visibility
  • ledger availability
  • skill drift or readiness nudges

​
potpie whoami

potpie whoami
Shows the current host identity. In local OSS mode this typically reports a none-style identity rather than a managed account subject.

​
potpie ui

potpie ui [OPTIONS]
Launches the local graph explorer served by the daemon.

​
Options

OptionTypeDescription
--open / --no-openboolOpen the explorer in a browser.
--potstrOpen the explorer against a specific pot.

​
Examples

potpie ui
potpie ui --pot default
potpie ui --no-open

​
potpie config

potpie config COMMAND [ARGS]...
Local config is persisted to <home>/config.json.

​
Subcommands

CommandPurpose
potpie config get <key>Read a stored config value.
potpie config set <key> <value>Persist a config value.

​
Examples

potpie config get backend.profile
potpie config set backend.profile falkordb
  1. Install the CLI with uv tool install potpie or pip.
  2. Run potpie setup.
  3. Verify readiness with potpie status --host.
  4. Connect integrations with provider-specific login commands.
  5. Register the current repository with potpie source add repo ..
  6. Use potpie ui or potpie resolve to start working with the graph.