{"protocol":"clank-doc/1","frameworkVersion":"0.8.0","slug":"cli","title":"Deployment CLI","description":"The clank executable contains both the compiler and deployment client. It does not install application dependencies or execute remote build hooks.","group":{"id":"deploy","title":"Deploy and operate"},"url":"https://docs.clank.run/docs/cli","source":"docs/cli.md","headings":["Interactive launcher","Create","Help and readiness","Authenticate","Projects","Workspaces and access","Workspace activity","Deploy and inspect","Status and rollback","Secrets","Local migrations","Automation"],"tableOfContents":[{"id":"interactive-launcher","title":"Interactive launcher","level":2},{"id":"create","title":"Create","level":2},{"id":"help-and-readiness","title":"Help and readiness","level":2},{"id":"authenticate","title":"Authenticate","level":2},{"id":"projects","title":"Projects","level":2},{"id":"workspaces-and-access","title":"Workspaces and access","level":2},{"id":"workspace-activity","title":"Workspace activity","level":2},{"id":"deploy-and-inspect","title":"Deploy and inspect","level":2},{"id":"status-and-rollback","title":"Status and rollback","level":2},{"id":"secrets","title":"Secrets","level":2},{"id":"local-migrations","title":"Local migrations","level":2},{"id":"automation","title":"Automation","level":2}],"markdown":"# Deployment CLI\n\nThe `clank` executable contains both the compiler and deployment client. It does not install application dependencies or execute remote build hooks.\n\n## Interactive launcher\n\nRun the command without arguments in a terminal:\n\n```sh\nclank\n```\n\nClank opens a dependency-free guided launcher for creating an app, checking the current project, logging in, deploying, or viewing every command. Creating an app presents the built-in templates and asks for the target directory.\n\nThe templates are:\n\n| Template | Direct command | Includes |\n| --- | --- | --- |\n| Authenticated Todo | `clank create my-app --template=auth-todo` | Auth, private SQLite data, SSR, hydration, Tailwind, migrations, and live sync |\n| Minimal full-stack | `clank create my-app --template=minimal` | SSR, hydration, reactive TypeScript, Tailwind, health checks, and deployment |\n\n`auth-todo` remains the default when `--template` is omitted. In a non-interactive terminal, bare `clank` prints the complete help instead of waiting for input. Agents and scripts should continue to use explicit commands and `--json` surfaces.\n\n## Create\n\n```sh\nclank create my-app\nclank create my-site --template=minimal\nclank create my-app --name=\"Customer workspace\"\ncd my-app\nnpm install\nnpm run dev\n```\n\nThe generated app includes auth, an owned Todo table, SSR, hydration, live updates, Tailwind, a health route, deployment configuration, its first migration, a human `README.md`, and an agent-oriented `AGENTS.md`. Its only dependency is the official `@clank.run/framework` package, which has no transitive dependencies. The exact CLI runtime is still embedded into deployment artifacts, so the platform never runs an install hook.\n\nUntil a Clank version is published, or while changing the framework and an app together, point the scaffold at the current checkout:\n\n```sh\nnode /path/to/clank/scripts/clank.mjs create my-app --framework=local\ncd my-app\nnpm install\n```\n\n`--framework` also accepts an explicit npm dependency spec, tarball, or `file:` path. Blueprint `plan` and `generate` accept the same option so their checksum includes the actual dependency choice.\n\n## Help and readiness\n\n```sh\nclank help\nclank deploy --help\nclank help --json\nclank doctor\nclank doctor --json\n```\n\nEvery command supports focused `--help` without authenticating or executing the command. Unknown commands and long options fail non-zero and suggest a close known spelling instead of being ignored.\n\n`doctor` validates the Node version, deployment configuration, compiled entry state, migration names and checksums, package scripts, CLI login, and local project link. Missing login or a first-deploy link is a warning, not a local-build failure. Its `clank-doctor/1` JSON report and the `clank-cli-help/1` command manifest are stable agent surfaces.\n\n## Authenticate\n\n```sh\nclank login\nclank whoami\nclank logout\n```\n\n`clank login` securely defaults to `https://clank.run`. The CLI prints the exact verification URL and a short code, then waits for browser approval. Use `clank login --server=https://deploy.example.com` only for an explicitly self-hosted control plane.\n\nPasswords never pass through the CLI. Profiles are stored under `${CLANK_HOME:-~/.clank}/config.json`. Set `CLANK_HOME` to isolate CI or test credentials.\n\nExisting Proact profiles and project links are imported automatically on first use. See [Renaming from Proact](renaming-from-proact.md).\n\nCredential profiles and project links are size-bounded, structurally validated, canonicalized to one server URL, written with owner-only permissions, and replaced atomically. Invalid local state fails closed without echoing token contents. Ordinary platform requests time out after 30 seconds; deployment uploads and health-gated activation time out after five minutes. JSON responses are UTF-8 validated and capped at 4 MiB before parsing.\n\n## Projects\n\n```sh\nclank project create my-app\nclank project create \"Customer workspace\" --slug=customer-workspace\nclank project list\nclank project link \nclank project delete [project-id] \\\n --confirm=\"delete-site \" \\\n --acknowledge-data-loss\n```\n\nLinks are written to `.clank/project.json` and should normally remain uncommitted.\n\nDeletion is permanent and requires an account-wide token plus an owner/admin organization role. Project-scoped tokens are rejected even if they have `tokens` permission. A successful deletion removes the matching local project link, but leaves other directories and off-platform copies untouched. See [Site deletion](deployment-platform.md#site-deletion).\n\n## Workspaces and access\n\n```sh\nclank org list\nclank org create \"Acme Engineering\" --slug=acme\nclank org members \nclank org invite person@example.com --role=developer\nclank org invitations \nclank org revoke-invite \nclank org accept \nclank org role \nclank org remove \n```\n\nInvitation creation prints its email-bound token once. Reissuing for the same email invalidates older tokens. Invitation lists contain identifiers and safe metadata, never tokens or hashes. Only owners and administrators can create/revoke invitations or change/remove members; only an owner can grant or change the owner role, and the last owner is protected.\n\n## Workspace activity\n\n```sh\nclank activity\nclank activity --org= --limit=100\nclank activity --before=\nclank activity --json\n```\n\n`clank audit` is an alias. The feed is newest first and includes the event ID, action, target, actor, timestamp, and safe audit metadata. `--json` prints the complete stable response for agents and automation. Owners, administrators, and developers can read events for their current organizations; viewers cannot. A project-scoped token needs `audit` permission and receives only that project's events.\n\n## Deploy and inspect\n\n```sh\nclank deploy\nclank deploy ../another-app\nclank deploy --dry-run\nclank deploy --output=/secure/path/release.clank.gz\nclank deploy --name=\"Customer workspace\" --slug=customer-workspace --org=\nclank deploy --json\nclank inspect /secure/path/release.clank.gz\n```\n\nDeployment validates config, runs the local build without a shell, packages included files plus the exact Clank runtime, verifies the artifact locally, creates and links a project if needed, uploads with a digest/idempotency key, and waits for migration and health. `--name`, `--slug`, and `--org` configure that automatic first project creation, so login plus one deploy command is sufficient.\n\n`--dry-run` is deliberately offline: it builds and writes a verified artifact without reading a login, creating a project, or contacting a platform. `--json` suppresses human progress output and emits one `clank-deploy-result/1` document with artifact, release, URL, and timing data.\n\nBefore upload the CLI stores a non-secret attempt record in `.clank/deploy-attempt.json`. If the connection fails after the platform may have accepted the artifact, the next identical deploy within 24 hours reuses the same idempotency key and converges on the original release. A definitive platform response clears the record.\n\n## Status and rollback\n\n```sh\nclank status\nclank releases\nclank releases delete \\\n --confirm=\"delete-release \"\nclank logs --limit=500\nclank rollback \nclank rollback --restore-data --confirm=\"restore \"\n```\n\n`clank releases` reports the retained artifact count and uncompressed runtime/snapshot bytes. Cleanup requires the token's `rollback` permission, never removes the active artifact, and preserves release metadata, logs, and audit evidence. Removing the active release's immediate predecessor also destroys code rollback and its matching data snapshot, so it additionally requires `--allow-rollback-loss`.\n\nLogs are bounded. Every non-empty known secret value is redacted, including short values, with longer overlapping values replaced first. Apps must still avoid logging credentials because transformed, encoded, split, or externally emitted values cannot be recognized reliably.\n\n## Secrets\n\n```sh\nprintf '%s' \"$API_KEY\" | clank secrets set API_KEY\nclank secrets set API_KEY --from-env=API_KEY\nclank secrets list\nclank secrets delete API_KEY\n```\n\nThere is deliberately no `secrets get`.\n\n## Local migrations\n\n```sh\nclank migrate plan\nclank migrate apply\n```\n\nProduction migrations always run inside the deployment transaction.\n\n## Automation\n\nUse `clank token create` to issue a short-lived project token containing only the CI job's required permissions, and isolate it with a dedicated `CLANK_HOME`. Membership and token scope are re-evaluated on every request; removing the member or revoking the token stops future access.\n\nSuccessful commands exit `0`; input, auth, build, upload, migration, or health failures exit non-zero. Commands that document `--json` emit structured failures to standard error with a stable code and message. Failed server revocation prevents `logout` from silently deleting the only local token reference. `--local` is for platform recovery.\n"}