CLI Reference

Synopsis

pizzapi [command] [options]

When called without a command, pizzapi starts an interactive coding session and streams it to the configured relay server.

Run pizzapi --help for a quick summary of all commands:

pizzapi v0.2.2 — PizzaPi coding agent

Usage:
  pizza                       Start an interactive agent session
  pizza web [flags]           Manage the PizzaPi web hub (Docker)
  pizza runner [args]         Manage the background runner daemon
  pizza runner stop           Stop the runner daemon
  pizza setup                 Run first-time setup
  pizza usage [provider]      Show API usage stats
  pizza models                List available models
  pizza plugins [cmd]         Manage Claude Code plugins (list/trust/untrust)

Flags:
  --cwd <path>    Set working directory
  --safe-mode     Skip MCP, plugins, hooks, and relay (fast startup)
  --no-mcp        Skip MCP server connections
  --no-plugins    Skip Claude Code plugin loading
  --no-hooks      Skip hook execution
  --no-relay      Skip relay server connection
  -v, --version   Show version
  -h, --help      Show this help

Run `pizza <command> --help` for command-specific help.

---

Commands

pizzapi (default)

Start an interactive pi coding session and relay it to the web UI.

pizzapi
pizzapi --cwd /path/to/project
pizzapi --safe-mode            # Skip MCP, plugins, hooks, relay
pizzapi --no-mcp               # Skip only MCP servers

Flag	Description
--cwd <path>	Working directory for the session (default: current directory)
--safe-mode	Skip all external dependencies (MCP, plugins, hooks, relay) for instant startup
--no-mcp	Skip MCP server connections only
--no-plugins	Skip Claude Code plugin discovery and loading
--no-hooks	Skip all hook execution
--no-relay	Skip relay server connection
--sandbox <mode>	Set sandbox mode: enforce, audit, or off. See Agent Sandbox.

The session ID is derived from the runner configuration and displayed on startup. Open the relay server’s web UI to watch the session live.

If no API key is configured and the relay is not disabled, the CLI will automatically launch the setup wizard before starting the session.

Startup Performance

MCP servers are initialized in parallel with per-server timeouts (default: 30 seconds). If a server doesn’t respond in time, it’s skipped and an error is shown.

When startup takes longer than 5 seconds, a warning is displayed in both the TUI and web UI showing which servers were slow. You can disable this warning by setting "slowStartupWarning": false in your config.

Tip

See the Safe Mode & Startup Performance guide for detailed troubleshooting, timeout tuning, and per-server diagnostics.

---

pizzapi setup

Run (or re-run) the first-time setup wizard. Prompts for the relay server URL, email, and password, then saves the API key to ~/.pizzapi/config.json.

pizzapi setup

Tip

You can re-run setup at any time to switch relay servers or update credentials.

---

pizzapi runner

Start the headless runner daemon. The daemon registers with the relay server and waits for session-spawn requests from the web UI or from agents using the spawn_session tool.

# Start the runner (foreground)
pizzapi runner

# Start the runner in the background
pizzapi runner &

# Stop a running daemon
pizzapi runner stop

See the Runner Daemon guide for detailed usage.

---

pizzapi runner stop

Send a stop signal to the currently running runner daemon.

pizzapi runner stop

---

pizzapi web

Start the PizzaPi web hub (relay server + web UI) using Docker Compose. This is the easiest way to self-host the relay — no need to clone the repo or configure Docker manually.

Run pizzapi web --help for the full usage:

pizza web — Manage the PizzaPi web hub (server + UI via Docker Compose)

Usage:
  pizza web [flags]               Start the web hub
  pizza web stop                  Stop the web hub
  pizza web logs                  Tail container logs
  pizza web status                Show container status
  pizza web config                Show current configuration
  pizza web config set <k> <v>    Update a config value

Flags:
  --port <port>       Set the host port (persisted to config.json)
  --origins <list>    Set extra allowed CORS origins (comma-separated, persisted)
  --tag <tag>         UI image tag from GHCR (default: latest)
  --build             Build UI locally (fallback mode)
  --dev-ui            Run the local dev UI stack (repo checkout only)
  -f, --foreground    Run in the foreground (don't detach)
  --no-cache          Rebuild Docker image without layer cache
  -h, --help          Show this help

Local dev UI stack (`--dev-ui` on a repo checkout):
  Runs the server and `dev:ui` together in Docker; the UI stays hot-reloaded on port 5173.

Docker build args (fallback mode):
  PREBUILT_UI (auto)    Set by pizza web based on the host prebuild result

Configuration (~/.pizzapi/web/config.json):
  port            Host port (default: 7492)
  vapidSubject    VAPID subject for push notifications
  extraOrigins    Extra CORS origins, comma-separated

# Start on the default port (7492)
pizzapi web

# Start on a custom port (persisted for future runs)
pizzapi web --port 8080

# Set extra CORS origins (persisted)
pizzapi web --origins "https://example.com,https://other.com"

# Pull a specific GHCR UI tag
pizzapi web --tag main

# Build the UI locally (fallback mode)
pizzapi web --build

# Run the local dev UI stack (repo checkout only)
pizzapi web --dev-ui

# Run in the foreground (don't detach)
pizzapi web --foreground

# Management
pizzapi web stop
pizzapi web logs
pizzapi web status

Note

Requires Docker with Docker Compose installed. If you’re not running from the PizzaPi repository, the command will automatically clone it to ~/.pizzapi/web/repo.

Tip

By default pizza web pulls ghcr.io/pizzaface/pizzapi-ui:latest before startup (or your --tag value). Use --build to keep the old local-build fallback behavior. Use --dev-ui if you want the hot-reloaded dev stack (bun run dev, which includes dev:ui on port 5173) from a local PizzaPi checkout.

Subcommand	Description
(none)	Build and start the relay server + web UI
stop	Stop the running web hub
logs	Tail the container logs
status	Show running container status
config	Show current configuration from config.json
config set <key> <value>	Update a config value (see below)

Flag	Description
--port <number>	HTTP port to expose (default: 7492). Persisted to config.json.
--origins <list>	Extra CORS origins, comma-separated. Persisted to config.json.
--tag <tag>	UI image tag to pull from ghcr.io/pizzaface/pizzapi-ui (default: latest).
--build	Build UI locally instead of pulling GHCR image (fallback mode).
--dev-ui	Run the local dev UI stack from a repo checkout.
--foreground, -f	Run in the foreground instead of detaching
--no-cache	Rebuild Docker image without layer cache
--help, -h	Show help

pizzapi web config

View the current web hub configuration:

pizzapi web config

pizzapi web config set

Update a configuration value. Changes are saved to ~/.pizzapi/web/config.json and take effect on the next pizza web start.

pizzapi web config set port 9000
pizzapi web config set extraOrigins "https://example.com"
pizzapi web config set vapidSubject "mailto:ops@example.com"

Key	Default	Description
port	7492	Host port to expose the web UI on
vapidSubject	mailto:admin@pizzapi.local	VAPID subject for web push notifications
extraOrigins	(none)	Extra allowed CORS origins, comma-separated

Tip

CLI flags like --port and --origins automatically persist to config.json, so you only need to pass them once. Use config set to change values without starting the server.

All settings and persistent data are stored in ~/.pizzapi/web/:

File	Purpose
config.json	All web hub settings (port, VAPID keys, origins, etc.)
compose.yml	Auto-generated Docker Compose config (regenerated each run)
data/	Persistent auth database

VAPID keys for push notifications are generated on first run and stored in config.json. They persist across restarts and config changes — push notification subscriptions won’t break.

Note

Custom Docker overrides: The compose.yml is regenerated on each run from the template + config. For additional Docker customizations (extra volumes, networks, etc.), create a compose.override.yml in the same directory — Docker Compose picks it up automatically.

---

pizzapi usage

Show API usage and quota information for your authenticated providers.

# Show usage for all providers
pizzapi usage

# Filter to a specific provider
pizzapi usage anthropic
pizzapi usage gemini

# Machine-readable JSON output
pizzapi usage --json

Anthropic (Claude)

For Anthropic OAuth subscriptions, the command fetches quota utilization from the Anthropic API:

Claude usage (OAuth subscription)
──────────────────────────────────────────────────────
  5-hour window            12.3%  (resets 2/24/2026, 2:15:00 PM)
  7-day window              8.1%  (resets 3/1/2026, 9:00:00 AM)
  7-day (OAuth apps)        4.2%  (resets 3/1/2026, 9:00:00 AM)
  7-day (Opus)              2.0%  (resets 3/1/2026, 9:00:00 AM)
  7-day (Sonnet)            6.5%  (resets 3/1/2026, 9:00:00 AM)

  Extra usage enabled
    Monthly limit:   $100
    Credits used:    $12.34
    Utilization:     12.3%

Gemini (Google Cloud Code Assist)

For Gemini OAuth credentials, the command fetches quota buckets from the Google Cloud Code Assist endpoint:

Gemini usage (Google Cloud Code Assist, OAuth)
  Project: my-project-123
──────────────────────────────────────────────────────
  INPUT / gemini-2.5-pro       85.0% remaining (850 left)  resets 3/1/2026, 12:00:00 AM
  OUTPUT / gemini-2.5-pro      92.3% remaining (923 left)  resets 3/1/2026, 12:00:00 AM

Tip

If no credentials are found, log in with /login inside a pizzapi session to authenticate with your AI provider.

---

pizzapi models

List all AI models available through the configured providers.

# Human-readable table
pizzapi models

# Machine-readable JSON
pizzapi models --json

Example output:

provider   model                    notes
---------  -----------------------  -----
anthropic  claude-opus-4-5          reasoning • 200,000 ctx • Claude Opus 4.5
anthropic  claude-sonnet-4-20250514            200,000 ctx • Claude Sonnet 4
google     gemini-2.5-pro           reasoning • 1,000,000 ctx • Gemini 2.5 Pro

---

pizzapi plugins

Discover and manage Claude Code plugins. PizzaPi can load plugins designed for Claude Code — their commands become slash commands, hooks map to pi lifecycle events, and skills are shared via the Agent Skills standard.

# List all discovered plugins (global + project-local)
pizzapi plugins

# Trust all untrusted local plugins in the current project
pizzapi plugins trust

# Trust a specific plugin directory
pizzapi plugins trust /path/to/plugin

# Remove a plugin from the trust list
pizzapi plugins untrust /path/to/plugin

# Clear the entire trust list
pizzapi plugins untrust

# Show the current trust list
pizzapi plugins trusted

# Show help
pizzapi plugins --help

Subcommand	Description
(none) / list	List all discovered plugins with trust status
trust [path]	Trust project-local plugins. No path = trust all untrusted in cwd.
untrust [path]	Remove from trust list. No path = clear entire list.
trusted	Show the current trust list from ~/.pizzapi/config.json

Trust model:

• Global plugins in ~/.pizzapi/plugins/, ~/.agents/plugins/, or ~/.claude/plugins/ are always auto-trusted — same as global skills or extensions.
• Project-local plugins in .pizzapi/plugins/, .agents/plugins/, or .claude/plugins/ under your project directory can execute shell commands via hooks. They require explicit trust before loading.

There are three ways to trust a local plugin:

1. CLI: pizza plugins trust (pre-approve before starting a session)
2. TUI: Interactive confirmation dialog at session start
3. Web UI: Amber trust banner with Trust / Skip buttons

Once approved by any method, the trust is persisted to ~/.pizzapi/config.json so future sessions auto-load without re-prompting.

Tip

See the Claude Code Plugins guide for details on plugin structure, hook mapping, and how the adapter works.

---

pizzapi --version

Print the installed version number and exit.

pizzapi --version
# pizzapi v1.2.3

---

Agent Tools

PizzaPi registers several tools that are available in every agent session:

Tool	Description
spawn_session	Spawn an independent agent session on the runner
list_models	List available models and providers
send_message	Send a message to another agent session
wait_for_message	Wait for a message from another session
check_messages	Non-blocking check for pending messages
get_session_id	Get this session’s ID
set_session_name	Set the session display name
update_todo	Update the session’s todo list
subagent	Delegate tasks to specialized subagents with isolated context

subagent

Delegate tasks to specialized subagent processes. Each subagent runs in its own isolated context window (separate pi process), keeping the parent session’s token budget lean.

Modes:

• Single: { agent: "name", task: "..." } — invoke one agent
• Parallel: { tasks: [...] } — run multiple agents concurrently (up to 4)
• Chain: { chain: [...] } — sequential execution with {previous} output substitution

Agent definitions are loaded from ~/.pizzapi/agents/*.md (user scope) and .pizzapi/agents/*.md (project scope).

See the Subagents guide for full documentation.

---

Global Flags

Flag	Description
--help, -h	Show help and exit
--version, -v	Print version and exit
--cwd <path>	Override working directory (applies to the default session command)

---

Internal Commands

These commands are used internally by the daemon and should not be called directly:

Command	Description
pizzapi _daemon	Internal daemon entrypoint (spawned by the supervisor)
pizzapi _worker	Internal worker entrypoint (spawned by the daemon for each session)
pizzapi _terminal-worker	Internal terminal PTY worker (spawned by the daemon for terminal sessions)