<!--
  scaffold: pa-cli-reference.md
  bucket: platform-tooling (Bucket 7)
  what belongs here: top-level `pa` bin overview. Point at `pa --help` as source of truth.
-->

# `pa` CLI — top-level reference

The `pa` bin is the operator-facing top-level CLI. Every verb here is a subcommand routed by the top-level dispatcher.

## Verbs (subject to change — `pa --help` is source of truth)

| Verb | Purpose |
|---|---|
| `pa session` | Start a PA session (chdir to agent dir, exec `claude`). |
| `pa status` | Probe operator content, installed package, workspace reachability, then desk overview. |
| `pa workspace <verb>` | Workspace server lifecycle (start / stop / status / restart / open). |
| `pa project <verb>` | Project state writes (create / status / doc add/rm/status / list). |
| `pa work <verb>` | Work-item state writes (create / status / list). |
| `pa knowledge <verb>` | Query the operator's knowledge graph (related / search / domain / orphans / path); `rebuild` deletes and rebuilds the per-device graph. |
| `pa autonomy <verb>` | Autonomy envelope get / set / list / init. |
| `pa environment [verb]` | Environment cache read / refresh / extended. |
| `pa lint <verb>` | Lint operator text against voice rules. |
| `pa gsc <verb>` | Google Search Console automation. |
| `pa staging-alias <verb>` | Canonical staging.<site> alias for CF Workers sites. |
| `pa migrate-inspect [options]` | Host inspection for migration planning. |
| `pa launch --agent=<n> --task=<id>` | Boot a scoped agent instance bound to an identity and task. |

Run `pa --help` for the current authoritative list. Verbs land as the operating model evolves; the docs here rot fast.

## Exit codes

Tooling standard § 6:

- `0` ok
- `1` usage error
- `2` operational failure
- `3` transport / IO failure

## When to reach for a specific verb

- **Session start** — `pa session`.
- **Status check on session boot** — `pa status` (then part of the greeting).
- **Managing work** — `pa work` (write) + `desk work` (read).
- **Managing projects** — `pa project` (write) + `desk projects` (read).
- **Looking up knowledge** — `pa knowledge`.
- **Managing autonomy state** — `pa autonomy`.
- **Environment refresh** — `pa environment refresh` (only when the env may have shifted; default `pa environment` reads cache).

## Related

- `desk-cli-reference.md` — read-only complement.
- `packages/cli/src/pa/cli.mjs` — source of truth for the verb dispatcher.
- `packages/core/docs/autonomy-envelope-tracker.md` — the `pa autonomy` mechanism.
- `environment-awareness.md` — the `pa environment` mechanism.