# CLI specification — command by command

**Derived from:** `packages/cli/src/` (actual implementation) · **As of:** 2026-07-10 · Built: `deploy`, `list`, `delete`, `signup`, `activate`, `whoami`, `init`, `inspect`, `plan`, `preview`, `prod`, `approve`, `verify`, `logs`, `rollback`, `feedback` (+ `--version`/`-v`/`version`, `help [command]`). The MCP server (BUILT, see MCP.md) wraps these same command functions. Account/API-key/quota subsystem (B3, SSOT D16): full spec in [ACCOUNTS.md](ACCOUNTS.md).

## Invocation & global behavior

```
openpouch <command> [--json] [--help]
```

- **`--json`**: exactly one JSON object on stdout — no prose, no colors. Errors too: `{"ok": false, "error": {"category", "message", "fix"}}` — categories: `usage`, `env`, `auth`, `quota`, `provider`, **`network`** (the openpouch API could not be REACHED at all — DNS/refused/timeout/TLS; the message names the host + cause and the fix gives a concrete connectivity check like `curl -sS https://openpouch.sh/healthz`, so a sandbox without egress is not mistaken for a broken app — Codex 2026-07-04), `policy-denied`, `approval-required`, `human-required`, `internal` —, plus an optional **`suggestedCommand`** (string) when there is exactly one unambiguous next command to run (e.g. `openpouch init`, `openpouch deploy dist`, `openpouch deploy .`) — so an agent can act on it directly instead of parsing the prose `fix`. It is omitted when the fix is an example, contains placeholders, or offers several options; the `fix` text is always present. Designed for agents; everything below documents these shapes.
- Without `--json`: short human-readable lines.
- **Universal `summary` field (PRD R3):** every result — success and error, in `--json` and in the MCP tool result — carries a top-level **`summary`** string right after `ok`: plain-language, jargon-free text written for a *non-technical* operator. The agent relays it to its human (verbatim if it likes); it says what happened, whether the app is live and healthy, and what (if anything) the human must do. In human (non-`--json`) output the same text is echoed after a blank line. Generated centrally in `src/summary.ts`. The MCP server additionally surfaces it as a leading `Relay this to your human:` text block (see MCP.md). *(One field is CLI-only: the optional top-level `feedbackHint`, added in the CLI's `render()` on error/dead-end results, is NOT present on MCP tool results — the MCP path never runs `render()`. Every other field, incl. `summary`/`error`/`suggestedCommand`, is identical across CLI `--json` and MCP.)*
- **The live link is the primary result (PRD R5):** on a successful deploy the live URL is promoted to a top-level **`url`** field (the instant lane also adds top-level **`claimUrl`**), so an agent never has to dig it out of a nested object before handing it to the human.
- **Exit codes:** `0` ok · `1` unexpected failure · `2` usage error · `3` manifest/policy missing or invalid · `4` auth (no/invalid key) · `5` provider error · `6` policy gate (`approval-required`, `policy-denied`, or `human-required`) · `7` deploy reached a terminal failed state · `8` deploy live but smoke/verify failed.
- **Providers:** the manifest's per-environment `provider` selects the adapter — `render`, `vercel`, or `openpouch-run` (the instant lane; key **optional** — anonymous by default, or under your account if an openpouch API key is set, B3). See `openpouch deploy` and [INSTANT-LANE.md](INSTANT-LANE.md).
- **Tuning env vars:** `OPENPOUCH_POLL_MS` (deploy status poll interval, default 5000 ms) · `OPENPOUCH_DEPLOY_TIMEOUT_MS` (poll timeout, default 600000 ms) · `OPENPOUCH_HOME` (overrides `~` for `.openpouch/` secrets — used by tests) · `OPENPOUCH_KEY_FILE` (full path of the openpouch-run account-key file, overriding the `~/.openpouch/openpouch-run.key` default — honoured by both the reader and `activate`'s writer).
- **Key resolution per provider** (never logged; provider comes from the environment's `provider` field in the manifest — the manifest decides the adapter): render → `RENDER_API_KEY` env var, else `~/.openpouch/render.key`; vercel → `VERCEL_TOKEN`, else `~/.openpouch/vercel.token` (+ optional `VERCEL_TEAM_ID` for team scope); **openpouch-run → `OPENPOUCH_API_KEY` env var, else the key file (default `~/.openpouch/openpouch-run.key`, override the path with `OPENPOUCH_KEY_FILE`); absent = anonymous (no Bearer sent), which is fine — the instant lane needs no account (PRD R5)**. `OPENPOUCH_HOME` overrides `~` (tests). Values are passed to the adapter and never appear in output, logs, or files. Missing-key errors are provider-specific. Exception: `init`'s service auto-match is Render-only today.
- Launcher: `bin/openpouch.js` is a plain Node script running the compiled build (`dist/main.js`); in the monorepo run `npm run build` first (without a build it exits 1 with that hint).
- Usage/help: `openpouch help` or `openpouch --help` prints usage and exits **0**; a bare `openpouch` with no command also prints usage but exits **2** (usage error). An unknown command exits 2.
- Version: **`openpouch --version`** (or `-v`, or `openpouch version`) prints `openpouch <version>` and exits **0**; with `--json` it returns `{"ok": true, "version": "<version>"}`. The version is the published `openpouch` package version, injected into the bundle at build time (so it always matches what was installed).

**npm/npx friction (Codex 2026-07-04).** `npx openpouch …` depends on npm's cache; on machines where `~/.npm` is root-owned or unwritable (a common sandbox artifact), `npm install`/`npx` fail before openpouch even runs. Agent-safe workaround — point the cache at a local writable dir: `npm_config_cache=.openpouch-npm-cache npx -y openpouch deploy --json` (or `npm install --cache <writable-dir>`). **Two more npx realities (Codex 2026-07-05):** (a) **parallel `npx openpouch` invocations can race the shared npm cache** (`ENOTEMPTY` rename errors) — run npx calls sequentially, or preinstall once so later calls skip npm entirely (`npm i -g openpouch`, or project-local `npm i -D openpouch` + `npx --no-install openpouch …`); (b) **every cold `npx` needs registry access** (including `npx openpouch --help`) — in offline/network-gated sandboxes preinstalling is the only robust path. This is environment friction, not an openpouch error, so openpouch can't fix it from inside; the same notes live in the website `llms.txt` so agents find them during discovery. **(c) npm's own update notices** print to stderr around openpouch's clean single-JSON stdout — harnesses that MERGE streams can see them interleaved with the JSON (Codex suite smoke 2026-07-05); when strict parsing matters, set `npm_config_update_notifier=false` (or preinstall, which skips npm at run time entirely).

**Command-specific help (OpenClaw 2026-07-04).** `openpouch <command> --help` and `openpouch help <command>` print that command's OWN page — usage line, applicable flags, one example, and the most common failure with the next command to run (every `--help` used to print the same global page, so an agent probing for exact syntax had to infer). Bare `--help` / `help` keep the global page; `help <unknown>` exits 2 and falls back to the global usage. With `--json` the help arrives as `{ok, command, help: [lines]}`.

## `openpouch deploy [dir] [--json]`

Zero-config **instant lane** (SSOT D11): packages a folder and deploys it to an anonymous ephemeral preview on openpouch's own infra — no account, no provider key, no manifest. The optional **`dir`** positional picks the folder (default: the current directory) — e.g. `openpouch deploy dist` ships a framework build output in one flow (`npm run build && openpouch deploy dist`, no `cd`). Returns a live `https://<slug>.openpouch.sh` URL, a `claimUrl`, and an `expiresAt` (unclaimed previews vanish after 72 h). Writes the deployment truth back into the **project root** (`deploy.manifest.json` with `preview` → provider `openpouch-run`, `deploy.policy.json`, `deploy.evidence.json`, `DEPLOYMENT.md`).

> **Claim-token privacy:** the `claimUrl` carries a single-use claim token — anyone who has that link can claim the preview, so it is a secret. It is kept out of everything that gets committed or relayed: **`deploy.evidence.json` and `DEPLOYMENT.md` do NOT contain it** (the evidence `notes` only points at where it lives), and the plain-language `summary` (written to be relayed to a human verbatim) never contains it either — so an agent can't leak it by pasting the summary into a public report/chat (Balerion/Claude 2026-07-01, hardening the OpenClaw 2026-06-29 flag). The full link is persisted to **`.openpouch/claim.json`** (`0600`; `.openpouch/` is auto-gitignored — local runtime state, never repo history) and is carried in the deploy `--json` as top-level **`claimUrl`** with **`claimUrlIsPrivate: true`**. So an agent relays the shareable **`url`**, and hands the human the `claimUrl` privately (re-readable later from `.openpouch/claim.json`).

**Redeploy semantics (each instant deploy is a fresh preview).** Running `deploy` again in a folder whose `deploy.manifest.json` was written by the instant lane (every env provider `openpouch-run`) **redeploys** — it does not error — so agents iterate deploy → fix → deploy. **But every instant deploy produces a NEW ephemeral URL/slug** (72 h, unclaimed): the instant lane has no in-place "update the same URL" primitive; the manifest is rewritten to point at the newest deploy. To keep one specific preview around longer, **`claim`** it — claiming extends it from 72 h to **7 days** (a claim link comes back with every deploy — see workflow 4); for a stable, *updatable* target, use the **governed lane** (bring-your-own Render/Vercel via `preview`/`prod`), whose URL is fixed. `deploy` only *refuses* (exit 2) when a **governed** manifest exists (an env with a `render`/`vercel` provider) → those projects use `preview`/`prod` instead. (A present-but-invalid manifest doesn't block and is overwritten.)

**Unbuilt-frontend guard:** deploying the current folder **without an explicit `dir`** is refused (exit 2) when it looks like an *unbuilt* frontend source tree — an `index.html` referencing source modules (e.g. `<script src="/src/main.jsx">`), or no `index.html` plus a build script and a `src/` dir. The error's `fix` names the build directory to deploy, and the error carries a machine-readable **`suggestedCommand`** — `openpouch deploy <buildDir>` if a build output already exists, otherwise `openpouch deploy .`. This prevents the silent failure of shipping source that 404s. **The guard does NOT fire when the folder has a server entry** — a `start` script, an existing `main`, or a conventional entry file (`server.js`/`app.js`/`index.js`/`main.js`/`*.mjs`): that makes it a full-stack/dynamic app, so a bare `openpouch deploy` ships the **whole** folder (the server runs and build-on-deploy builds the frontend) instead of steering to `deploy dist`, which would drop the backend. The CLI mirrors run-d's server-entry precedence so both agree on what "dynamic" means. An **explicit path also bypasses the guard** — `openpouch deploy .` forces the current folder as-is.

Target API override: `OPENPOUCH_RUN_API` (default `https://openpouch.sh`). Full spec of the lane + server: [INSTANT-LANE.md](INSTANT-LANE.md).

**The server classifies the upload** (the CLI sends the same tarball either way): a static site is served as files (M1); a Node app with a start command is **built and run in a hardened container** (M2) when the host has the dynamic lane enabled. The JSON `deployment.kind` is `"static"` or `"dynamic"`; for a dynamic app the human output notes "running in a container", and a failed build returns a provider error with logs. Because the deploy is a single call, a dynamic app can come back while its container is **still starting** (`status` `building`/`queued`) — surfaced as `pending` (see below). Detection rules + the runtime are in [INSTANT-LANE.md](INSTANT-LANE.md) §M2.

**Build-on-deploy (PRD L9):** when a project has a `build` script, the server runs `npm run build` (in a hardened throwaway container) so you don't have to pre-build locally — for **dynamic** apps after install and before start (e.g. an Express server serving a Vite/React build), and for **unbuilt static SPAs** (a Vite/CRA frontend with *no* server) by building and then serving the build output (`dist`/`build`/`out`) as files. A failing build returns a provider error with the build logs (also via `openpouch logs`, tagged `[build]`). **Guard interaction:** the client-side unbuilt-frontend guard still refuses a *no-explicit-dir* `openpouch deploy` of an unbuilt SPA (so older servers don't silently serve source) — pass the folder explicitly (`openpouch deploy .`) and the server builds it. Building locally and `openpouch deploy dist` also still works.

**Env vars / secrets (`--var`, `--env-file`):** give a dynamic app env vars — `openpouch deploy --var KEY=value` (repeatable) and/or `--env-file <dotenv>` (`--var` overrides the file). Keys must match `[A-Za-z_][A-Za-z0-9_]*`; `PORT`/`HOME` are reserved; a small cap guards the box (≤50 vars, ≤4 KB total). **The values are secrets (D7):** they ride in a request header (never the body/URL), are injected into the container as env, and **never appear in any output, log, evidence file, or the JSON** — only the NAMES surface (top-level `envVars: [...]` + a human `env:` line). **argv caveat:** only **`--env-file`** keeps values out of the process argument list; a value passed inline with **`--var KEY=value` IS in argv** (visible to `ps`/other local processes on the same machine), so for real secrets prefer `--env-file`. **Dotenv files are never uploaded:** `.env`, `.env.*` (at ANY depth, e.g. `packages/api/.env`), and the `--env-file` file itself are excluded from the upload tarball — they are read locally to build the header and are never shipped to the box or served. The exclusion does not rely on `tar`'s glob-anchoring (which differs across `tar` builds — GNU tar would otherwise leak a nested dotenv): `collectDotenvExcludes` walks the tree and emits an exact-path exclude per dotenv file, so it's identical on every platform. **Ephemeral:** env lives only while the container exists — it survives scale-to-zero (stop/start) but NOT a box reboot (a recreated container has no env); persistent/encrypted secrets are a later paid-lane increment. Applies to **dynamic** apps (a static upload has no running process). *(Server-side: needs run-d + the `op-docker` wrapper with env support — an owner box rollout.)*

**Report-safe output (`--redact-secrets`):** `openpouch deploy --redact-secrets` leaves the claim link OUT of the result entirely — top-level `claimUrl` is dropped (replaced by `claimUrlRedacted: true`), `deployment.claimUrl` is omitted, and the human `claim:` line reads `[redacted]`. Use it when the whole `--json` result (or terminal output) will be pasted into a public report, chat, or PR: with no token in it, there is nothing to leak. The real link is still saved to **`.openpouch/claim.json`** (`0600`) as usual, so the human/agent re-reads it there — nothing is lost. Belt-and-suspenders over the always-on `claimUrlIsPrivate` flag (which tells a careful agent not to paste the link); `--redact-secrets` makes an accidental paste impossible.

**Full-stack health path (`--health-path <p>`, OpenClaw 2026-07-04):** a full-stack app can serve `/` while its API is dead — the shell loads, the backend 500s. `openpouch deploy --health-path /api/health` holds the deploy to its own API bar: after the `GET /` gate passes, the CLI ALSO probes the given path (origin-relative, must start with `/`); a non-200 turns `healthStatus` to `degraded` with a `nextStep` naming the path, and the probe outcome is reported as top-level `healthPathCheck: {path, passed, httpStatus?}`. The path is recorded as the manifest `healthcheck` (so a later `openpouch verify` re-checks it automatically) and as `healthPath` on the evidence record. No auto-guessing: openpouch never probes `/api/health` uninvited — a 404 on a guessed path would be a false alarm (the honest default stays `GET /`). **Rule of thumb for agents (Codex 2026-07-05): if the app has ANY server route, pass `--health-path` on the FIRST deploy** — without it the standard workflow proves only `/`, and API breakage stays invisible until someone curls the route by hand.

**Long runs are silent in `--json` by design (Codex 2026-07-05):** a `deploy`/`verify` with `--json` prints nothing until the single final JSON object (so stdout stays parseable). A 30–60 s dynamic deploy therefore LOOKS stalled while install/build run. To watch progress live, run `openpouch logs --json --limit 50` from a second shell — the phases stream there in real time (`[install]`/`[build]`/`[app]`, with real durations). A streaming NDJSON mode (`--json-stream`) is a considered post-launch candidate, not shipped — this note is the honest current answer.

JSON output: `{ok, summary, url, authenticated, claimUrl, claimUrlIsPrivate, envVars?, pending, healthStatus, healthPathCheck?, nextStep?, nextCommands: {verify, logs, inspect}, dataDurability?, deployment: {id, url, claimUrl, expiresAt, status, kind: "static"|"dynamic", framework: string|null, buildCommand?, startCommand?, httpStatus?}, evidence: [files]}` — **`nextCommands`** (OpenClaw 2026-07-05) carries copy-paste follow-up commands so agent loops stay mechanical instead of reconstructing flags; `nextCommands.verify` includes `--health-path <p>` automatically when the deploy ran with one. The same object rides along over MCP (`openpouch_deploy`). The generated `DEPLOYMENT.md` resume checklist and self-repair runbook name the exact health-path-aware verify command too (omitting the flag also works — `verify` applies the manifest healthcheck automatically). — with `--redact-secrets` the `claimUrl` is absent both top-level (→ `claimUrlRedacted: true`) and inside `deployment`. `url`/`claimUrl` are promoted to the top level (R5); **`authenticated`** (boolean) tells the agent whether the deploy ran under an openpouch account (a Bearer key resolved) or anonymously — mirrors `whoami`, derived from key resolution, no secret shown (Codex 2026-07-01); **`claimUrlIsPrivate: true`** flags the claim link as a secret (it carries a single-use save token) so an agent doesn't paste it into a public report or chat — the shareable address is `url`, never `claimUrl` — and the plain-language `summary` (R3) describes the claim link as private **without ever printing it**, so a relayed summary can't leak the token (the link is persisted privately to `.openpouch/claim.json`). `deployment.framework`/`buildCommand`/`startCommand` come from the same detector as `openpouch init` (so `inspect` and the recorded manifest aren't `framework: null` for a Vite/Next/Express app), and they're persisted into `deploy.manifest.json` (`project.framework`, `build.{buildCommand,startCommand}`). When the deploy folder is **genuinely tracked** in a git repo, the source commit (`git rev-parse HEAD`, no remote needed) is recorded on the evidence record and shown in `DEPLOYMENT.md`; an **untracked** folder — e.g. a throwaway app sitting inside an ancestor workspace repo — records **no commit** (`—`), because the ancestor's HEAD has nothing to do with the deployed files and recording it would be false audit assurance.

**Failure-path legibility (0.2.15, from the standing agent-suite's first run — OpenClaw 2026-07-05).** Three behaviors make FAILED deploys as agent-readable as successful ones: **(1) `error.failureLogs`** — when a dynamic (or static-build) deploy fails on the server, the captured build/startup output travels back on the error (last 40 lines, additive field in `error`; also appended to the human output). This is deliberate: a failed instant deploy is removed server-side, so there is no record for `logs`/`inspect` to fetch afterwards — the error itself is the one window where the agent sees WHY, and the `fix` says "fix the cause shown, then rerun the same deploy command (each redeploy gets a fresh URL)" instead of pointing at service status. **(2) Preflight: invalid `package.json`** — a present-but-unparseable `package.json` exits 2 (`usage`) naming the JSON parse problem BEFORE any upload (it used to be classified fail-safe as *static* and shipped as a degraded preview, spending a quota slot); an absent `package.json` stays fine (plain static site). **(3) Preflight: empty directory** — exits 2 (`usage`) with concrete guidance before any upload; the server-side "no files" 400 keeps a usage-grade fix and maps to `usage`/exit 2 as backstop.

**Detect-and-surface data durability (PRD L10 / D20).** The detector also flags whether the app **writes data to local disk**, from several high-confidence signals: an embedded-database/local-store dependency (`better-sqlite3`/`sqlite3`/`@databases/sqlite`/`lowdb`/`nedb`/`diskdb`/`lokijs`/`node-persist`/`level`/`pouchdb`/`multer`), **Prisma with a local SQLite datasource** (the `schema.prisma` `provider = "sqlite"`), a **database file bundled at the project root** (`*.sqlite`/`*.db` — the strongest signal, the data is literally there), or source-level disk writes (`fs.writeFile`/`appendFile`/`createWriteStream`, a `.sqlite`/`.db` file reference, `new Database(`). External-DB clients (Postgres/MySQL/Mongo/Redis — incl. Prisma with a remote provider) are **not** flagged — that data lives elsewhere and is durable; the concern is *silent local loss*. When the app stores data locally, the deploy adds top-level **`dataDurability: {storesData: true, ephemeral: true, signals: […]}`** and the `summary` warns, in plain words, that an ephemeral preview does **not** keep that data (cleared on redeploy/expiry) — so nobody loses data silently (the Render lesson). It promises no persistent feature (there isn't one yet). `openpouch init` surfaces the same signal in `detected.dataPersistence` plus a hint.

**Deploy-health gate (`healthStatus`).** A container reporting `status: "live"` only means it *started*, not that it *serves* — e.g. an Express server handing back an unbuilt React `dist/` answers `200`-from-the-server-but-`404`-on-`/`. So on a live deploy the CLI runs a short **GET / smoke check** against the returned URL before declaring it shareable, and reports the outcome in the top-level **`healthStatus`**:

- **`"pending"`** — the deploy came back still `building`/`queued` (a dynamic container is starting), so it isn't reachable yet and isn't probed; `pending: true`, and `nextStep` tells the agent to wait and `openpouch verify` before sharing (R9.10). The `summary` reads "is being deployed … in a few moments" rather than "now live".
- **`"healthy"`** — `GET /` returned 200. `pending: false`, no `nextStep`, `summary` says it's "now live … anyone can open it right away". (Static deploys reach this immediately.)
- **`"degraded"`** — the container is live but `GET /` did not return 200. `ok` stays `true` (the deploy itself didn't fail) but `pending: false`, `deployment.httpStatus` carries the observed code, and `nextStep` points the agent at `openpouch logs` → fix → redeploy → `openpouch verify`. The `summary` says the app "isn't loading correctly yet … not ready to share" — it never invites sharing the dead link. This is the **"deploy ok ≠ app healthy"** guard: an agent that doesn't run `verify` itself still won't relay a broken URL.

The probe **polls** `GET /` until 200 or a budget elapses, because a dynamic container can briefly 502/404 right after "live". Budget: env `OPENPOUCH_INSTANT_SMOKE_TIMEOUT_MS` (ms, default `15000`); set `0` to disable the check (then a live deploy is reported `"healthy"` without probing).

If an account key is configured, the deploy runs under that account (it counts toward the account's quota; see `whoami`). **When a quota limit is reached** the deploy fails with `error.category: "quota"` and a `fix` that names the *actionable* path, **split by auth context** (Hermes suite 2026-07-05): an **authenticated** caller gets the self-service path `openpouch list` → `openpouch delete <name>` to free a slot yourself (Befund #8 — the agent clears its own quota instead of waiting for the 72h sweep), plus `openpouch whoami` for current usage; an **anonymous** caller is told explicitly that anonymous previews **can't be deleted manually** — each frees its slot when it expires (~72h) — so the real options are waiting for a slot to roll off or `openpouch signup` (which unlocks list/delete self-service and higher tiers).

## `openpouch signup [--email <addr>] [--github] [--json]`

Create an openpouch account (B3 / SSOT D16). Anchor = **email OR GitHub** (the human picks). Agent-completable end-to-end for email (no dashboard, PRD R4); GitHub needs the human to approve in a browser. No human check / CAPTCHA on our side (R8). Full flows: [ACCOUNTS.md](ACCOUNTS.md) §5/§7.

- `--email <addr>`: starts an email signup → the server emails a verification link; returns the account id + the `activate` command to finish. JSON: `{ok, summary, method: "email", accountId, message, devVerifyToken?}` (`devVerifyToken` only when the server runs with `OPENPOUCH_RUN_DEV_TOKENS=1`).
- `--github`: prints the GitHub authorize URL to open in a browser. JSON: `{ok, summary, method: "github", startUrl}`.
- Neither flag → exit 2 (usage).
- **Email already registered (server 409):** exit **2** (`usage`) with the message "an openpouch account for `<email>` already exists" and a `fix` pointing at `openpouch whoami` (check/reuse the existing account) or using a different email. It is a usage conflict, **not** a provider outage — the generic provider wording ("the deployment may have expired…") never applies here (Befund K, 2026-07-01).

## `openpouch activate --account <id> --token <token> [--json]`

Completes an email signup: activates the account and **saves the issued API key to the key file (default `~/.openpouch/openpouch-run.key`, chmod 600)** so future deploys are keyed automatically (PRD R4).

**Key path:** `--key-file <path>` (this run) or `OPENPOUCH_KEY_FILE` (env, also used by every reader) override the default location; deploys pick a custom location up via `OPENPOUCH_KEY_FILE` or `OPENPOUCH_API_KEY`.

**Data-loss guard:** the key file is written **only** when it is absent, empty, or already holds an openpouch key. If anything else is there — most importantly a private key (the 2026-06-21 incident: a misplaced SSH key at this path was overwritten and destroyed) — `activate` **refuses to write** rather than overwrite, with `saved:false` and a `reason`. This is the default, non-interactive behaviour (no TTY prompt): destroying a file is never the silent outcome. When an existing **openpouch** key is replaced, the prior key is first copied to `<path>.bak` (0600).

Secret discipline (rule 7): the JSON carries only the non-secret `keyPrefix`. The raw key appears in the output (under `key`) **only** when it could not be saved — a write failure *or* the guard refusing — because the verification token is single-use and the key would otherwise be lost; that case also carries `saved:false` + `reason`. JSON: `{ok, summary, account, keyPrefix, saved, keyPath? | (reason, key)?}`. Exit codes: missing `--account`/`--token` → **2** (usage); an invalid/expired verification token (server auth error) → **4** (auth); any other provider failure → **5** (provider).

## `openpouch whoami [--json]`

Shows the account behind the configured API key — tier (plan) + current usage — or that the caller is anonymous. Read-only; agent-usable (also an MCP tool, R8). The key is resolved from `OPENPOUCH_API_KEY` / `~/.openpouch/openpouch-run.key` and never echoed. JSON when keyed: `{ok, summary, authenticated: true, account, tier: {name, deploysPerHour, deploysPerDay, maxLiveDeployments, maxBytes, maxDynamic}, usage: {liveDeployments, dynamicDeployments, deploysLastHour, deploysLastDay}}`; when anonymous: `{ok, summary, authenticated: false}`. A presented-but-invalid/revoked/suspended key → exit 4 (`auth`).

## `openpouch list [--json]`

Lists the live instant-lane apps owned by the configured account key — name (slug), kind (static/dynamic), status, live URL, and expiry. Read-only; agent-usable (also an MCP tool, R8). Needs an account key: anonymous callers aren't grouped under an account, so they get an empty list + a signup pointer (not an error). The key is resolved from `OPENPOUCH_API_KEY` / `~/.openpouch/openpouch-run.key` and never echoed; the result carries **no capability token** (claim/mgmt) — only the public fields (D7). JSON when keyed: `{ok, summary, authenticated: true, count, deployments: [{id, slug, status, url, kind, createdAt, expiresAt, claimed, runtimeStatus?}]}`; when anonymous: `{ok, summary, authenticated: false, count: 0, deployments: []}`. A presented-but-invalid key → exit 4 (`auth`).

## `openpouch delete <name> [--json]`

Deletes one of your OWN instant-lane apps by name (slug) → frees a quota slot. The self-service answer to a "limit reached" (quota) error: list your apps, delete an unused one, redeploy — instead of waiting for the 72h sweep (Befund #8). **Owner-only:** it needs your account key, and run-d verifies the app belongs to that account — a key can never delete another account's (or an anonymous) app. Deleting an ephemeral preview is **not** a governed-production action, so it needs no approval and is agent-usable (R8, D13); there is no interactive confirmation (an agent has no TTY; the app is re-creatable with `openpouch deploy`). Errors: missing/invalid name → exit 2 (`usage`, with `suggestedCommand: "openpouch list"`); no key → exit 4 (`auth`); the name isn't on your account → exit 5 (`provider`, with a `fix` pointing at `openpouch list`). JSON on success: `{ok, summary, slug, kind?}`.

## `openpouch init [--force] [--json]`

Detects the project, writes `deploy.manifest.json` + `deploy.policy.json` (default policy: previews autonomous, production gated). **Idempotent:** if a manifest exists and `--force` is absent, nothing is written (`alreadyInitialized: true`, exit 0).

Detection (from actual code, `src/detect.ts`):
- `project.name`: package.json `name`, else directory basename.
- `framework`: first match in dependency order next→`nextjs`, astro, nuxt, @sveltejs/kit→`sveltekit`, @remix-run/node→`remix`, vite, express/fastify/hono/koa→`node`; fallback `node` if a package.json with a name exists.
- `build.buildCommand` / `startCommand`: package.json `scripts.build` / `scripts.start` verbatim.
- `env[]`: source scan (≤400 files, ≤512 KB each, depth ≤6, skips node_modules/.git/dist/build/.next/coverage/.vercel/.turbo and dot-dirs) for `process.env.X` and `import.meta.env.X` (X = `[A-Z][A-Z0-9_]+`). `NODE_ENV` excluded; `PORT` included with `required: false` ("Injected by the platform at runtime"). Sorted by name.
- **Provider auto-match** (best effort, never blocks init): if a key resolves, `listServices()` and match by normalized name (lowercase alnum; unique exact match, else unique substring match either direction) → maps `environments.production` `{provider: "render", serviceId, url?, branch?}`. No/ambiguous match or API error → hint instead.
- The generated manifest is validated against the openpouch schema before writing (self-check; failure = exit 1 internal bug).
- **AGENTS.md upsert (D13):** init creates or updates a marked section (`<!-- openpouch:start/end -->`) in the project's `AGENTS.md` — the cross-harness standard file — describing deployment truth files, commands, the MCP alternative, and the you-cannot-approve rule. Existing content outside the markers is never touched; the section is replaced idempotently (result reported as `agentsMd: created|updated|unchanged`). Runs also on already-initialized projects (section refresh without touching manifest/policy).

JSON output: `{ok, summary, alreadyInitialized?, created?: [files], agentsMd: "created"|"updated"|"unchanged", detected: {name, framework|null, buildCommand|null, startCommand|null, envVars: [names], dataPersistence: {storesData: boolean, signals: [strings]}}, production: {serviceId, url|null} | null, hints: [strings]}` — `detected.dataPersistence` is the L10/D20 data-durability probe (embedded-DB deps / `fs` writes / `.sqlite`/`.db` references; empty `signals` + `storesData:false` when none).

## `openpouch inspect [--json]`

Answers: **what is deployed, where, on which commit, which env vars are missing** — without a dashboard.

- No manifest → exit 3, fix: "Run `openpouch init` first." Invalid manifest → exit 3 with path-prefixed schema errors.
- A key is required only if at least one environment has a `serviceId` (else exit 4 with fix).
- Per mapped environment: `getService`, `getRecentDeploys(5)` (liveDeploy = first with status `live`, else newest), `getEnvVarNames`.
  - `envVars.runtimeIntrospection`: `"available"` when the provider API can be asked about env vars; `"unavailable"` on the instant lane (the box API deliberately exposes nothing — even NAMES can leak intent).
  - `envVars.present` (only when introspection is available): provider var names with non-empty values (names only — values never cross the adapter).
  - `envVars.missingRequired`: manifest vars with `required: true` applicable to this environment (`environments` filter) that are absent/empty on the provider. When introspection is `"unavailable"`, this is computed from **local deploy evidence** instead: required manifest vars minus the `deployProvided` names of the latest deploy.
  - `envVars.extraOnProvider` (only when introspection is available): provider vars not in the manifest at all (**drift detection**).
- Environments without `serviceId` → `status: "unmapped"` + hint.
- Provider errors map to exit 4 (`auth`) or 5 (`quota`/`provider`) with the adapter's `fix` hint passed through.

JSON output: `{ok, url?, summary, project: {name, framework|null}, environments: {<name>: {provider, status: "ok"|"unmapped", service?: {id, name, url?, branch?, runtime?, suspended}, liveDeploy?: {id, status, commit?, commitMessage?, at?}, envVars?: {runtimeIntrospection: "available"|"unavailable", present?, missingRequired, extraOnProvider?, deployProvided?}}}, hints}` — `summary` reads e.g. "Here's the current status of …: • production: live at <url>. It still needs these settings: …".

**Top-level `url` (Hermes 2026-07-05).** `deploy` and `verify` carry the live URL top-level; `inspect` used to have it only nested under `environments.<name>.service.url` — harnesses look top-level first. `inspect` now also carries a top-level `url`: the **primary** service URL — `production`'s when it has an active (non-suspended) service with a URL, else `preview`'s, else any other mapped environment's. Omitted (not `null`) when no environment has one. Additive; the nested shape is unchanged.

**Deploy-provided env vars (`deployProvided`, OpenClaw 2026-07-04) + honest introspection shape (OpenClaw 2026-07-05).** Vars passed at deploy time via `--var`/`--env-file` used to be invisible here: the deploy said they were set, the runtime provably had them, and `inspect` said `present: []` — a trust-breaking contradiction. The instant lane deliberately never exposes env vars via its API (even NAMES can leak intent, e.g. `STRIPE_SECRET_KEY`), so `inspect` reads the NAMES from the local evidence (`deploy.evidence.json` → `envVarNames` of the environment's latest record) and reports them as `envVars.deployProvided: [names]` (values never exist anywhere readable). Since 2026-07-05 the shape itself is honest about what it can know: on the instant lane `envVars.runtimeIntrospection` is `"unavailable"` and **`present`/`extraOnProvider` are omitted entirely** — an empty `present: []` used to read like "your vars are gone" when the truth was "cannot look". `missingRequired` stays meaningful there (evidence-based, see above), and a `hint` names `deployProvided` as the source of truth. The human line reads `env: runtime introspection n/a on the instant lane | deploy-provided (--var/--env-file): …`.

## `openpouch plan [--json]`

Per mapped environment: the deploy action (`deploy-preview` for preview, else `deploy-production`), the policy decision, blockers (no serviceId, policy denies, missing required env vars, no API key), `ready` flag, and concrete `nextSteps` (including the approval path). Exit 0 even when blocked — `plan` reports, it never acts. **Instant-lane (`openpouch-run`) environments are special-cased** (OpenClaw 2026-06-29): they have no plan/approval/env-var gate, so their `nextSteps` point at `openpouch deploy` and `openpouch verify` (not `preview`/`prod`), and a `hint` notes that `plan`/`preview`/`prod` target bring-your-own Render/Vercel projects.

JSON: `{ok, summary, project, environments: {<name>: {action, decision, mapped, missingRequired, ready, blockers, nextSteps}}, hints}`

## `openpouch preview` / `openpouch prod [--json]`

The governed deploy pipeline: **policy check → (approval) → rollback anchor → trigger → poll → smoke → evidence writeback.**

1. Loads manifest + policy (missing policy → safe defaults with hint). Environment must have a `serviceId` (else exit 3).
2. `evaluateAction(policy, env, action)`:
   - `denied` → exit 6, category `policy-denied`.
   - `requires-approval` → looks for a usable approval (approved, matching action+environment+serviceId, unexpired, **valid HMAC signature**). Found → consumed (single use) and the deploy proceeds with `approvedBy` recorded. Not found → creates (or reuses) a pending request in `.openpouch/approvals.json` and exits 6 with category `approval-required` and `approvalRequest: {id, …}` — the fix tells the agent to ask a human for `openpouch approve <id>`.
   - `allowed` → proceeds (default policy allows preview).
3. Records the current live deploy id as `rollbackAnchor`, triggers the deploy, polls `getDeploy` until `live`/`failed`/`canceled` or timeout.
4. If live and the environment has a `url`: smoke check (manifest `healthcheck`, else `GET /` expecting 200).
5. Appends a `DeploymentRecord` to `deploy.evidence.json` and rewrites `DEPLOYMENT.md` — always, also on failure.

Exit: 0 live (+smoke ok) · 7 deploy failed · 8 live but smoke failed. JSON: `{ok, summary, url?, deployment: DeploymentRecord, smokePassed, smokeSkipped?, note?, evidence: [files]}` — `url` is present (top level, R5) only when the deploy went live and the environment has a URL; `summary` reflects live+healthy / live-but-unhealthy / failed, and notes when it went out with human approval. **`smokeSkipped`/`note` (R9.5):** if the deploy went live but the environment has no `url` to test, the smoke check is skipped — `smokePassed` is `null`, `smokeSkipped:true`, and `note` says how to enable it (add the env's `url`, then `openpouch verify`). The `summary` then says it couldn't be checked rather than implying it's healthy, so "live but unchecked" is distinguishable from "live + healthy".

## `openpouch approve [id] [--json]`

Without id: lists pending, unexpired requests (`{ok, summary, pending: [...]}`) — **a safe, read-only listing any agent may run**; `approve --json` with no id never approves anything (made explicit on a Hermes field-test request, 2026-07-06). With id: **requires an interactive terminal** — in non-TTY contexts (agent harnesses) it exits 6 with category `human-required`. On TTY: y/N confirmation, then the request is signed (HMAC-SHA256 over `id|action|environment|serviceId|requestedAt|expiresAt`, keyed by `~/.openpouch/approver.secret`, auto-created `0600`) and marked `approved` with `approvedBy` = OS username. Requests expire 24 h after creation; approvals are single-use (consumed by the deploy). Both the list and the approve/declined results carry `summary` (R3).

## `openpouch verify [--env <name>] [--health-path <p>] [--json]`

Runs the smoke check against the environment's manifest `url` (default env when `--env` is omitted: the deploy's environment — `production` if the manifest has one, otherwise the single mapped environment, e.g. an instant-lane `preview`; see [§Default environment](#default-environment-no---env)). Appends the results to the **latest** evidence record of that environment — the one documented exception to append-only (smoke results aggregate on the latest record; history is never rewritten). Exit 0 pass · 8 fail · 3 if the environment has no `url` (the exit-3 `fix` is actionable, not just "edit the file": it points at `openpouch inspect` to find the provider's URL, or deploying first to record it — R9.1). JSON: `{ok, summary, environment, url, checks: [{name, passed, url?, detail?}], evidenceUpdated}` — `summary` reads as "Good news — … is healthy" or "Heads up — … has a problem (<detail>); N of M checks passed".

**Configurable healthcheck.** By default the smoke check is `GET /` expecting `200`. To verify a different route or status — e.g. an API whose `/` is intentionally 404 but `/health` returns 200 — set a top-level **`healthcheck`** in `deploy.manifest.json`: `{"path": "/health", "expectStatus": 200, "timeoutMs": 10000}` (`path` must start with `/`; `expectStatus` 100–599, default 200; `timeoutMs` > 0, default 10000 — see [DATA-MODEL.md](DATA-MODEL.md) §1). `openpouch verify` and the governed `preview`/`prod` smoke step honour it. **Both paths are proven (OpenClaw 2026-07-04):** when the effective health path is not `/` itself — from `--health-path <p>` (a one-off override, wins over the manifest) or a non-`/` manifest `healthcheck` — `verify` checks **`GET /` AND `GET <path>`** and passes only when both do: a full-stack app can serve the shell fine while its API is dead, so proving one never silently skips the other. `openpouch deploy --health-path <p>` writes the manifest `healthcheck` for you, so the re-check is automatic from then on.

## `openpouch logs [--env <name>] [--limit <n>] [--json]`

Structured runtime logs of the mapped service (default env when `--env` is omitted: the deploy's environment — `production` if present, else the single mapped one, e.g. an instant-lane `preview`, see [§Default environment](#default-environment-no---env); default limit: 50). Adapter detail: Render's `/v1/logs` requires the owner id — resolved once per adapter instance via the service object and cached. Output: `{ok, summary, environment, serviceId, count, requestedLimit, logs: [{timestamp?, message}]}`. For an instant-lane **dynamic** app these include the deploy's lifecycle markers **plus the captured install and app startup output**, each line tagged `[install]`/`[app]` — so `openpouch logs` after a `degraded`/failed deploy shows the actual cause (install error, crash, or a server serving an unbuilt frontend), which is what drives the self-repair loop. Use `--limit` to widen the tail. **`count` < `requestedLimit` means you already have the full available tail** — there is no pagination and the daemon keeps a bounded window per phase, so a large `--limit` returning fewer lines is not a dropped flag, there just isn't more (a Codex field test 2026-07-06 read `--limit 120` → `count: 25` as "limit ignored"); `requestedLimit` echoes the effective limit so that distinction is machine-readable (present from the release after 0.2.15). **Log messages are ANSI-stripped** — build/runtime tools emit color codes, removed so `--json` output and relayed text stay clean (OpenClaw 2026-06-29).

**Timestamp semantics (OpenClaw 2026-07-04).** Phase events stamp the moment they actually happened (an injected clock in run-d's orchestrator), and each milestone carries its real duration — `dependencies installed (took 8231 ms)`, `app build ok (took 1204 ms)`, `live (container …, port …, ready in 950 ms)`. Captured OUTPUT lines of a phase share that phase's END timestamp: the engine returns install/build output in one piece, so the block's capture time is the honest per-line time available (the store keeps every timestamp strictly increasing on top). Before this, every event reused the request's arrival time, which made `logs` useless for timing diagnosis. *(Server-side: lives in `packages/run` → needs the box rollout to be live.)*

## `openpouch rollback [--env <name>] [--json]`

Redeploys the **rollback anchor** — the commit of the deploy that was live before the latest one (recorded in the latest evidence record of the environment). Provider-portable primitive: `triggerDeploy(serviceId, {commitId})` (Render has no public rollback endpoint; deploy-by-commit is the rollback). Approval-gated like any write action (default policy: production rollback requires approval). Requires a prior openpouch deploy with a recorded anchor (else exit 3). On success the new deploy is appended to evidence with `notes: "rollback to <commit> (anchor <dep>, superseding <dep>)"`. Exit codes identical to `prod`. JSON: `{ok, summary, url?, rolledBackTo: {commit, anchorDeploy}, deployment: DeploymentRecord, smokePassed}` — note it differs from `prod`'s shape (adds `rolledBackTo`, and does not include `prod`'s `evidence: [files]` array). `summary` reads "I restored your <env> app to the previous working version. It's live again at <url>."

**Instant lane has no rollback (R9.2):** on an instant-lane project (the environment's provider is `openpouch-run`) there is never a rollback anchor — each `openpouch deploy` ships a fresh ephemeral preview, not a versioned release. `rollback` then exits 3 with the tailored message "instant-lane previews can't be rolled back" and a `fix` pointing at the move that works: fix the issue and `openpouch deploy` again. (This is detected before the generic "no anchor" path, so the agent isn't sent chasing an anchor state that can't exist.)

## `openpouch feedback "<text>" [--json]`

The **optional, opt-in** friction-feedback channel (PRD R10.3). It exists so an agent can, *at a friction moment*, report what tripped it up — it is never required and never part of a normal flow (R10.1: a successful command stays silent). Records **only the human's own typed note** (secret-free — never project content, never secrets, never what was deployed). JSON: `{ok, summary, recorded, sent}` (or `{ok, recorded: false, reason: "opt-out"}` when opted out). Empty text → exit 2.

- **Discovery (R10.3):** error/dead-end results carry a top-level **`feedbackHint`** field inviting this command. It appears *only* on failures (where the agent already pauses), never on success, and is omitted entirely when opted out. It is an agent-legible field, not a prompt — it blocks nothing.
- **Opt-out (R10.5a):** set `DO_NOT_TRACK=1` (or `OPENPOUCH_NO_FEEDBACK=1`) — the hint disappears and `feedback` records nothing.
- **No silent transmission (R10.5c):** by default the note is written only to a local outbox (`~/.openpouch/feedback.outbox.jsonl`). It is POSTed only when `OPENPOUCH_FEEDBACK_URL` is set — which the published CLI does **not** set, so nothing leaves the machine until the privacy policy covers it and an endpoint is deliberately configured. **Passive friction telemetry (R10.2/R10.4) is not shipped** — it lands only behind that same privacy-policy gate.

## Default environment (no `--env`)

`verify`, `logs`, and `rollback` accept `--env <name>` — the two environments openpouch creates and governs, **`preview`** and **`production`** (the names the CLI and the MCP enum advertise; R9.9 — no tempting door that nothing opens). The manifest schema (`ENVIRONMENT_NAMES`, see [API.md](API.md)) additionally accepts **`staging`** for governed BYO lanes, and the CLI honours it if a manifest maps it; the **MCP `environment` enum deliberately hides `staging`** (an agent shouldn't pick a name nothing produces, R9.9), but the CLI accepts it. When `--env` is **omitted**, openpouch resolves the target from `deploy.manifest.json` instead of hard-coding `production`:

1. **`production`** if the manifest defines it — the governed-lane default is unchanged.
2. else the **single** mapped environment — an instant-lane deploy writes only `preview`, so `openpouch logs` / `openpouch verify` straight after `openpouch deploy` just work.
3. else **`preview`** if present; else `production` (which then surfaces the normal "environment not mapped" error).

An explicit `--env` is always used verbatim. Rationale: a freshly-deployed instant preview has no `production` environment, so the old hard default produced a misleading "add `production.serviceId`" error for agents.

## Local state file: `.openpouch/approvals.json`

`{version: 0, requests: ApprovalRequest[]}` — see DATA-MODEL.md §4. Lifecycle `pending → approved → consumed` (or `expired`). The directory is auto-added to the project's `.gitignore` (runtime state, not repo history; the audit trail lives in `deploy.evidence.json`).

## Examples

```bash
npx openpouch init --json     # zero-config setup incl. service auto-match
npx openpouch inspect         # human summary
npx openpouch inspect --json  # for agents: single JSON object
```

Verified live (2026-06-12): in a fresh directory named like a real Render service, `init` auto-matched the service and `inspect` reported the live commit + env state through the CLI.