CLI Contract

Command Structure

The pam binary uses clap 4.5 derive for command parsing.

Global Flags

--json: Output format as JSON (applies to all list/show commands)
--config <path>: Override config file path (highest priority — see 060-configuration.md § Precedence Order)
--api-url <url>: Override central orchestrator URL (highest priority; default for CLI commands: http://127.0.0.1:7898)
--token <token>: Override bearer token (highest priority)
-h, --help: Display help
-V, --version: Display version

Command Inventory

Core Commands

`pam serve`

Start the central orchestrator (API server and dashboard).

pam serve [--bind <ADDR>] [--port <PORT>] [--database-url <DSN>] [--config <PATH>]

Flags:

--bind <ADDR>: Bind address (default: 0.0.0.0, env: PAM_BIND)
--port <PORT>: Server port (default: 7898, env: PAM_PORT)
--database-url <DSN>: PostgreSQL connection string (env: PAM_DATABASE_URL; required — no default)
--config <PATH>: Config file path (default: <platform data dir>/config.toml, env: PAM_CONFIG)

Semantics: Serves the embedded SPA (Rust/WASM — Leptos), the HTTP API, and the worker registry; owns the only PostgreSQL connection. Workers connect outbound to this process. Runs until Ctrl+C.

`pam migrate`

Run database migrations.

pam migrate [--database-url <DSN>]

Flags:

--database-url <DSN>: PostgreSQL connection string (env: PAM_DATABASE_URL)

Semantics: Applies pending migrations against PostgreSQL. Idempotent if already applied.

`pam doctor`

Health check for installation and dependencies.

pam doctor

Semantics: Checks central API reachability, PostgreSQL reachability (when run on the orchestrator host with a DSN configured), local tmux availability (relevant on worker hosts), config validity. Exits 0 if healthy, 1 if issues found.

Worker Commands

`pam worker`

Run the worker agent on an execution host.

pam worker --name <HOST_NAME> [--api-url <URL>] [--config <PATH>]

Flags:

--name <HOST_NAME>: Host name as registered centrally (required; must match a pam host add record)
--api-url <URL>: Central orchestrator base URL (env: PAM_API_URL; required — no default)
--config <PATH>: Worker config path (default: <platform data dir>/worker.toml, env: PAM_WORKER_CONFIG)

Semantics: Registers with the central orchestrator over an outbound connection (no inbound listener), then executes dispatched runs in local tmux sessions on socket pam. Authenticates with the worker token (PAM_WORKER_TOKEN env or the platform data dir worker-token file) provisioned by pam host add. Runs until Ctrl+C.

Host Commands

`pam host add`

pam host add <name> --platform <PLATFORM>

Arguments/Flags:

<name>: Unique host name (required)
--platform <PLATFORM>: macos or linux (required)

Semantics: Creates the host record (status: registered) and prints a worker token to install on that host. The token is shown once — store it in the worker host’s worker-token file.

`pam host list`

List worker hosts with status and last-seen time.

`pam host disable` / `pam host enable`

Exclude a host from dispatch / return it to the pool.

`pam host rotate-token`

Issue a fresh worker token for an already-registered host (OQ-10, confirmed, 071-risks-and-open-questions.md).

pam host rotate-token <name>

Arguments:

<name>: Host name to rotate (required; must already exist)

Semantics: Mints a new worker token, prints it once (same one-time-display contract as pam host add), and records its fingerprint on hosts.token_fingerprint. The previous token keeps working until the worker actually presents the new one — there is no forced grace-period cutover — so restart the worker on <name> with the new token promptly after rotating. See 061-security.md for the full token-rotation procedure and when to use it (suspected leak, routine credential hygiene, offboarding a host).

`pam host clear-suspect`

Clear a host’s instance-suspect flag (OQ-14, confirmed, 071-risks-and-open-questions.md).

pam host clear-suspect <name>

Arguments:

<name>: Host name to clear (required; must currently have hosts.instance_suspect = true)

Semantics: An operator trust-transfer action. Clears hosts.instance_suspect and hosts.instance_flagged_at, and accepts the instance_id most recently presented by that host as the new pinned value — so use it only after confirming (out of band) which of the two machines presenting the same worker token is the legitimate one. See 002-data-model.md for the detection algorithm this clears the output of.

Project Commands

`pam project add`

Create a new project.

pam project add <name> [--slug <SLUG>]

Arguments:

<name>: Project name (required)

Flags:

--slug <SLUG>: URL-friendly slug (auto-generated from name if omitted)

Semantics: Creates project record in database. Returns project ID.

`pam project list`

List all projects.

pam project list [--status <STATUS>]

Flags:

--status <STATUS>: Filter by status (active, archived)

Output: Table format (id, name, slug, status, created_at) or JSON.

`pam project show`

Display project details.

pam project show <id>

Arguments:

<id>: Project ID or slug

Semantics: Shows project metadata, work item count, recent activity.

`pam project archive`

Archive a project.

pam project archive <id>

Arguments:

<id>: Project ID or slug

Semantics: Soft-deletes project (status → archived). Work items remain intact.

Task Commands

`pam task add`

Create a new task, epic, milestone, or subtask.

pam task add <title> --project <id> [--parent <id>] [--kind <KIND>]

Arguments:

<title>: Work item title (required)

Flags:

--project <id>: Parent project ID (required)
--parent <id>: Parent work item ID (for epics/subtasks)
--kind <KIND>: Item type (task, milestone, epic, subtask; default: task)

Semantics: Creates work item. If --parent specified, creates hierarchical relationship. Path computed from parent chain.

`pam task list`

List work items.

pam task list --project <id> [--kind <KIND>] [--status <STATUS>]

Flags:

--project <id>: Project ID (required)
--kind <KIND>: Filter by kind (task, milestone, epic, subtask)
--status <STATUS>: Filter by status (todo, doing, done, cancelled)

Output: Tree view showing hierarchy, or flat list with path column.

`pam task show`

Display work item details.

pam task show <id>

Arguments:

<id>: Work item ID

Semantics: Shows description, status, assignee, parent/child relationships, associated runs.

`pam task move`

Move work item across board columns.

pam task move <id> --status <STATUS>

Arguments:

<id>: Work item ID

Flags:

--status <STATUS>: New status (todo, doing, done, cancelled)

Semantics: Updates work item status. Triggers work_item.status_changed event. Legal transitions follow the work-item transition table in 002-data-model.md — including todo → done directly: a task completed without ever entering doing (finished out-of-band, or its run completed while auto_mark_done is off) does not need to pass through Doing first.

`pam task board`

Display Kanban board for project.

pam task board <project-id>

Arguments:

<project-id>: Project ID

Output: Four-column layout (todo/doing/done/cancelled) with work item counts.

`pam task done`

Mark task as completed.

pam task done <id>

Arguments:

<id>: Work item ID

Semantics: Shortcut for pam task move <id> --status done. Valid from both todo and doing (see the transition table in 002-data-model.md) — a task does not need to sit in doing first. Typical use: work completed out-of-band, or a run finished while auto_mark_done was off and the item was never moved.

Run Commands

`pam run start`

Start a new AI provider session.

pam run start --task <id> --provider <provider> [--host <NAME>] [--cwd <PATH>]

Flags:

--task <id>: Task or Subtask ID (required)
--provider <provider>: Provider name (claude, codex, grok, gemini; required)
--host <NAME>: Target worker host name (optional; default: auto-select an online host)
--cwd <PATH>: Working directory path on the target host (default: the worker’s configured working root)

Semantics: Creates run record, dispatches to the target host; the worker there spawns the tmux session pam-<8hex>. Returns run ID, host, and session name. Provider wrapper CLI launched in session.

`pam run list`

List runs.

pam run list [--task <id>] [--status <STATUS>]

Flags:

--task <id>: Filter by task ID
--status <STATUS>: Filter by status (pending, spawning, running, exited, failed, stopped)

Output: Table with run ID, task ID, provider, session name, status, started/finished timestamps.

`pam run logs`

View run logs.

pam run logs <id> [--follow]

Arguments:

<id>: Run ID

Flags:

--follow: Stream logs in real-time (like tail -f)

Semantics: Streams tmux session output via capture-pane. Follow mode polls every 1s.

`pam run stop`

Stop a running session.

pam run stop <id>

Arguments:

<id>: Run ID

Semantics: Sends termination signal to tmux session. Status updates to stopped.

`pam run pane`

Display terminal pane snapshot.

pam run pane <id>

Arguments:

<id>: Run ID

Semantics: Captures current terminal state via tmux capture-pane. Displays as text. Not suitable for ANSI rendering (use web UI for that).

`pam run attach`

Attach to tmux session directly.

pam run attach <id>

Arguments:

<id>: Run ID

Semantics: For a run executing on the local host, execs tmux -L pam attach -t <session_name> for direct terminal takeover (detach with Ctrl+B, D). For runs on remote worker hosts, the CLI cannot reach the remote tmux socket — use the web UI’s relayed attach (WebSocket PTY relay through the orchestrator).

Note: This is the local terminal attach mode. For web-based attach (any host), see the WebSocket attach protocol in 030-http-api.md. For tmux mechanics, see 010-tmux-executor.md.

Provider Commands

`pam provider list`

List available AI providers.

pam provider list

Output: Table with provider ID, name, enabled status, configured status.

`pam provider doctor`

Test provider configuration and health.

pam provider doctor [<provider-id>]

Arguments:

<provider-id>: Provider ID (optional; if omitted, checks all configured providers)

Semantics: Tests provider CLI availability, API key configuration, basic connectivity. Returns detailed health report.

Hidden Commands

`pam exec run <run_id>`

Internal foreground execution wrapper for tmux sessions.

pam exec run <run_id>

Arguments:

<run_id>: Run ID

Semantics: Session’s foreground execution wrapper. Reads the run + provider config, normalizes/injects environment variables (including proxy base URLs), spawns the provider CLI, and POSTs run.started / run.finished{exit_code} to the internal signals endpoint, then holds the pane open for approximately 5 minutes for observation. Not exposed in help.

Note: Direct tmux attach is a separate path: pam run attach execs tmux -L pam attach -t <session_name> locally.

Environment Variables

Environment variables are the third-priority source for core CLI settings — below a CLI flag and below a config file value, above the built-in default. Full four-source order (resolves OQ-16): 060-configuration.md § Precedence Order.

Environment Variables

Note: The platform data dir — ~/Library/Application Support/pam/ on macOS, ~/.local/share/pam/ on Linux, resolved via the directories crate (ADR-011) — holds config.toml and token on the central host, and worker.toml, worker-token, providers.toml, and runs/ on worker hosts.

Configuration File

Config file location: platform data dir (~/Library/Application Support/pam/config.toml on macOS, ~/.local/share/pam/config.toml on Linux)

Sections (orchestrator):

[server]
bind = "0.0.0.0"
port = 7898

[database]
url = "postgresql://pam@localhost:5432/pam"

[providers]
catalog_path = "<platform data dir>/providers.toml"

Worker config (worker.toml on each execution host):

[worker]
name = "dev-mac"
api_url = "https://pam.example.internal:7898"

[providers]
catalog_path = "<platform data dir>/providers.toml"

Providers catalog (separate TOML file): format is owned by 020-provider-adapters.md — see its “Provider Catalog” section for the canonical schema (id, bin, argv_template, env map, completion hooks config).

pam project list --json

Returns:

{
  "projects": [
    {
      "id": "abc123",
      "name": "My Project",
      "slug": "my-project",
      "status": "active",
      "created_at": "2026-08-29T12:34:56Z"
    }
  ]
}

Relationships to Other Components

HTTP API (central orchestrator): ALL CLI commands — PM domain (project/task/board) included — call the central HTTP API using PAM_TOKEN (ADR-007, superseded 2026-08-29: direct store access would spread PostgreSQL credentials to every CLI host)
Worker: pam worker runs on each execution host and executes dispatched runs; pam run attach and pane access flow through the orchestrator’s relay (see 030-http-api.md)
tmux executor: workers own the tmux mechanics on their host; see 010-tmux-executor.md
Provider adapters: pam provider doctor invokes adapter-specific health checks against the host’s catalog; see 020-provider-adapters.md

Keyboard shortcuts

pam — Design & Architecture Docs