CLI reference
The @putnami/cloud extension adds the Cloud commands below. This inventory
names every top-level command and every nested verb exposed by their help.
The Key flags column is deliberately selective: use
putnami cloud <command> --help for the installed command's complete flags.
Commands that return records support --output=jsonl for scripts and agents.
Deploy and release
| Command | Does | Key flags |
|---|---|---|
putnami deploy |
Publish a deployable project and release a revision | --env, --wait, --timeout, --preview, --force, --image-version |
putnami publish |
Build and publish selected project artifacts, config, migrations, archives, and site-content members | --env, --archives, --namespace, --dry-run, --skip-publish-config, --skip-publish-migration, --skip-publish-doc |
putnami cloud deploy |
Direct/synchronous deploy path; can re-read a release with deploy status <release-id> |
--app, --env, --wait, --preview, --force |
putnami cloud sync |
Compare the complete branch state with provider and deployment-ledger observations; mutate only with --apply |
--env, --apply, --wait, --prune, --allow-dirty (non-production only) |
putnami cloud status |
Show the continuous-delivery (CD) header of each environment, then project, environment, serving revision, and health, plus each project's last run: its status, trigger, and failure reason | --env, --workspace, --provenance, --health |
putnami cloud env doctor [<env>] |
Check every prerequisite continuous delivery needs for one environment and print the fix for each one that is not met. Read-only; exits 1 when any check is missing or the control plane does not answer. Any other check that could not be run reads unknown and does not fail the command |
--env, --strict, --workspace, --output=json |
putnami cloud env enable [<env>] |
Apply every workspace-owned prerequisite of one environment (namespace bindings, environment definition, Runtime grants), report the operator-only rows with their fix, then print the doctor table. A second run writes nothing; exits 1 when a step failed or a row is still missing |
--env, --source-revision, --workspace, --output=json |
putnami cloud status starts with one CD line for the --env environment
(prod by default). The line names every channel the environment follows and
what the newest move of that channel did:
CD prod ← canary: gen 42 converged 2026-09-18T10:02Z (rs_ab12cd34…)A move that deployed nothing or only part of the environment also shows its
reason, and a move Control is still delivering reads in flight. When the header
cannot be read, the line reads CD prod: unavailable (<reason>) and the table
still prints. Structured output carries the same data under channel_follow.
The LAST RUN, TRIGGER, and REASON columns describe each project's most
recent run in its environment, failed runs included, while HEALTH keeps
describing the last successful release. They are read from the 100 most recent
runs of each environment; a project whose last run is older shows -.
TRIGGER reads cli for a run no channel move opened, and unknown when
Control could not read its channel-move records.
putnami cloud status --env prod --health answers "is prod on main and
healthy". It adds three columns to the rows of the --env environment. Rows of
other environments show - in them.
| Column | Shows |
|---|---|
ERRORS (10m) |
The number of log entries at severity ERROR or above in the last 10 minutes |
TOP ERROR |
The most frequent of those messages: the message or msg field of a JSON entry, else the text, cut to its first line |
ON MAIN |
yes, no, or unknown: whether the served commit is on main in your local checkout |
The errors come from one logs read for the whole environment, not one read per
service. The read stops after three pages of up to 1,000 entries each. When
more entries remain, every count is a lower bound: the cell reads N+ (for
example 12+), a note line above the table says so, and structured output sets
health.logs.capped. Entries with no service label, or
with a label that matches no row, are counted in a note line and never added to
a row. When the logs cannot be read (a machine token, which cannot read logs,
an older control plane, or a backend error), the note reads
Errors prod: unavailable (<reason>), the error cells show -, and the command
still succeeds.
ON MAIN compares the served commit with origin/main, or main when
origin/main does not exist, in your local checkout. It never fetches, so run
git fetch first for a current answer. It reads yes when the commit is on
main and no when your checkout has the commit and it is not on main. A pull
request head that was squash-merged reads no: that exact commit is not on
main. It reads unknown when no commit is recorded, the directory is not a git
checkout, there is no main ref, or your checkout does not have the commit.
Structured output carries every field, including the reason for each
unknown, under the health key; without --health that key is absent.
putnami cloud env doctor prints one row per prerequisite: ok, missing, or
unknown, each with its fix, then a summary line such as
not ready: 3 missing, 1 could not be checked. It exits 1 when a row is
missing or the control plane does not answer; with --strict it also exits
1 on any unknown row, which is the form to use as a CI gate. Before the first deploy
lists the checks and the rows that can answer unknown.
putnami cloud env enable applies every fix the workspace owns among those rows
and reports the rest, then prints the same table. Each write reads the current
revision first and sends it as the expected revision, so a second run writes
nothing. It needs platform.workspace.manage; a session without it is refused
before any write. Enable the environment in one command
lists what each row gets.
Identity and workspace
| Command | Does | Key flags |
|---|---|---|
putnami cloud login |
Sign in with OAuth device authorization | --no-open, --client-id, --scope |
putnami cloud logout |
Clear local Cloud credentials and revoke reachable registry tokens | |
putnami cloud whoami |
Show the active identity | --output=jsonl |
putnami cloud setup |
Link the repository, install Intelligence/audit wiring, and report discovered hosted Intelligence availability | --workspace, --workspace-name, --environment, --intelligence, --audit, --intelligence-workspace, --force-audit, --no-cache, --auto |
putnami cloud token |
Mint a workspace, global operator, cache, or registry bearer for a script | --global or --for cache|npm|go|oci|put |
putnami cloud tokens |
Create, list, or revoke workspace-owned machine tokens | create, list, revoke |
putnami cloud source |
Connect, inspect, or disconnect the workspace GitHub repository; expose numeric-id operator recovery | connect, status, disconnect, operator/break-glass bind, unbind |
Hosted CI and producer tracks
| Command | Does | Key flags |
|---|---|---|
putnami cloud ci |
Enable the subscription; inspect, start, cancel, retry, and diagnose runs; operate recovery modes | enable|disable|subscription, list|view|logs, start|cancel|retry, status|usage|insights|timings, repair|pause|drain|resume |
putnami cloud track |
Follow a producer channel or pin an immutable release set, optionally changing the runner channel atomically | --namespace, exactly one of --channel or --release-set, optional --runner-channel |
Run IDs may be shortened to any unambiguous prefix. CI mutations require
--reason; pass --yes as well in a non-interactive environment. See
Hosted CI for the setup and recovery path.
Configuration and data access
| Command | Does | Key flags |
|---|---|---|
putnami cloud config |
Inspect resolved project config or its published schema | --schema, --key, --env, --secret-keys, --with-secrets |
putnami cloud validate-config |
Validate local authored Config inputs without packaging or network access | [project], --env, --schema-from, --namespace |
putnami cloud secrets |
Manage workspace and project secrets | --block, --field, --from-stdin, --from-file, --reveal, --yes |
putnami cloud db |
Inspect databases, manage time-boxed access, or open a local bridge | list, info <db>, grant request|list|revoke, connect, --database, --level, --reason, --ttl |
putnami cloud sql-proxy |
Operator/emergency Cloud SQL Auth Proxy path | --instance, --port |
Observability and delivery evidence
| Command | Does | Key flags |
|---|---|---|
putnami cloud logs |
Query or live-tail application logs | --app, --since, --level, --follow, --cursor |
putnami cloud metrics |
Query application metric series | --app, --window, --from, --to, --cursor |
putnami cloud traces |
Query traces and filter slow requests | --app, --slow, --from, --to, --cursor |
putnami cloud report |
Submit a delivery-run conclusion for the current pushed commit | --conclusion, --exit-code, or -- <cmd…>; optional --status |
putnami cloud audit-attest |
Get, set, or batch-prefetch immutable Intelligence audit attestations | get|set|prefetch, --repo, --project, --group, --input-hash, --rubric-hash |
putnami cloud intelligence |
Inspect the operator index ledger or manage workspace subscription reviews, owner credentials, and workers | status, review doctor|status|launch|pause|resume|reconcile|cancel, review auth, review worker |
The complete cloud intelligence review command families are:
| Family | Verbs |
|---|---|
| Review control | doctor, status, launch, pause, resume, reconcile, cancel |
| Owner credentials | auth login, auth replace, auth status, auth revoke for codex or claude-code |
| Review workers | worker enroll, worker list, worker revoke, worker run |
Registries and cache
| Command | Does | Key flags |
|---|---|---|
putnami cloud registries |
Configure registry endpoints, inspect stored key state, or revoke legacy credentials | setup, status (also the default), logout, optional --registry |
putnami cloud distribution |
Manage namespace bindings, read grants, and public mirror targets | bindings activate|list, grants create|list|revoke, mirrors add|list|remove|rotate-credential |
putnami cloud registry-token |
Mint your registry bearer for one known host | --host, --materialize |
putnami cloud oci |
Copy, retag, or revert OCI images server-side | copy <src> <dst>, retag <ref> <tag…>, revert <repo>:<channel> |
putnami cloud cache |
Show or disable remote-cache configuration | status (also the default), disable, optional --remove |
Advanced publication inputs
| Command | Does | Key flags |
|---|---|---|
putnami cloud release-set |
Serve exact immutable release-set provider operations from a private request document | resolve|release|channel-set|channel-status, --request-file <absolute-mode-0600-file> |
putnami cloud image-layers |
Produce or verify the deterministic tarballs declared by an image project's image-layers.json |
--project, --check |
These are lower-level seams used by publication and image packaging. Prefer
putnami publish and putnami package for the normal project workflow.
Direct publishers
| Command | Does | Key flags |
|---|---|---|
putnami cloud publish-config |
Register an app schema and publish conf/env.<env>.yaml |
--app, --env, --dry-run |
putnami cloud publish-migration |
Publish a workload migration bundle | --app, --bundle-from, --namespace, --bundle-version, --dry-run |
putnami cloud publish-archives |
Publish pre-built extension archives as one immutable Put version | --app, --archives-from, --binary-name, --dry-run |
putnami cloud publish-doc |
Publish every docs/<site>/<section>/ tree as a site-content bundle |
--source, --section, --channel, --dry-run |