CLI reference

Every command that produces output supports --json for machine-readable results. Commands that talk to the platform default to https://api.cloudbed.dev; override with --api <url> or the CLOUDBED_API environment variable.

Authenticated commands check CLOUDBED_TOKEN first, then saved credentials in ~/.cloudbed/auth.json.

JSON errors

Any command run with --json prints failures to stderr as:

{"error":{"code":"unauthorized","message":"Missing bearer token."}}

The command exits nonzero. Branch on error.code; see Deploying with an agent for the code table.

Project

`cloudbed new <dir> [--template todo|guestbook|webhook|blog]`

Scaffold a capsule in <dir> from a template (default todo). Templates are complete working apps: server schema + queries + mutations, a Preact client, and shared types.

todo / guestbook — classic live-query UIs.
webhook — an API-first webhook inbox: path-param HTTP endpoints (POST /hooks/:source) feeding a live dashboard.
blog — a server-rendered public blog (ssr: true): curl-readable pages, agent-driven publishing via mutations.

`cloudbed init [dir] [--template todo|guestbook|webhook|blog] [--json]`

Add Cloudbed capsule files to an existing directory. init supports non-empty directories, never overwrites files, and merges the cloudbed dependency into an existing package.json.

`cloudbed dev [dir] [--port 3000] [--host <ip>] [--fresh]`

Run the capsule locally on the real production runtime under local workerd, with live reload on changes to server/, client/, and shared/. Prints app: http://localhost:<port>.

Local state persists across restarts in .cloudbed/state; pass --fresh to reset it.

--host binds a different interface than localhost — for example a Tailscale IP (--host 100.64.0.7) or 0.0.0.0, so you can develop on a remote box and open the app from another machine.

`cloudbed build [dir] [--json]`

Bundle the server and client and emit the deploy artifact into .cloudbed/build/. deploy does this for you; build is useful for checking the artifact (and its size — see limits) without deploying.

Deploying

`cloudbed deploy [dir] [--password <pw> | --no-password] [--api] [--json]`

Deploy the capsule and print its URL.

Logged out: creates an anonymous deploy — prints url:, a claim: link, and expires:. Credentials for later claiming and inspecting are stored in .cloudbed/deploy.json (gitignored).
Logged in: creates or updates an owned deploy and writes a cloudbed.json binding you can commit, so future deploys from the same directory update the same app.

--password <pw> gates the deployed capsule behind a shared visitor password; --no-password removes the gate; passing neither keeps the current setting. See password protection for how visitors and agents unlock.

If the artifact defines scheduled jobs and the deploy is anonymous, deploy prints a warning: schedules only fire after cloudbed claim. The cron definitions are still deployed, and local dev still runs them while cloudbed dev is active.

With --json, the response includes deployId, url, name, mode, claimed, passwordProtected, crons, createdAt, updatedAt, expiresAt, and, on create, one-time claimToken / inspectToken fields. Re-running deploy updates the existing deploy in place.

`cloudbed claim [dir] [--json]`

Claim an anonymous deploy to your account (run cloudbed login first). Claiming makes the deploy permanent, enables outbound fetch and server env, invalidates the one-time claim token, and writes the cloudbed.json binding. See Deploys & limits.

`cloudbed inspect [dir-or-deploy-id] [--json]`

Read a deploy's metadata: deploy:, url:, name:, mode:, and expires: when anonymous. Accepts a directory (default: cwd) or a raw deploy id. When .cloudbed/deploy.json contains an inspect token, it can authenticate private inspect routes and include deployed queries, mutations, and logs.

`cloudbed logs [dir-or-deploy-id] [--follow] [--after <seq>] [--url <capsule-url>] [--token <inspect-token>] [--json]`

Read a deploy's captured ctx.log entries (one line per entry: time, level, message, data). Resolves the deploy and inspect token like data-explorer: from .cloudbed/deploy.json in the app directory, or point at a capsule origin directly with --url (e.g. a running cloudbed dev server, where inspect routes are open) plus --token for a hosted capsule.

--follow polls every 2 seconds and prints only new entries, keyed by each entry's seq cursor — the missing half of the dev→deploy debugging loop. With --json, one-shot mode prints the raw {entries:[...]} response and follow mode prints NDJSON (one entry per line). --after <seq> starts from a known cursor. Note the runtime keeps at most 1000 recent entries, so a quiet --follow session can miss nothing but a bursty one starts from the retained window.

`cloudbed cron ls [dir] [--api <url>] [--json]`

List a deploy's scheduled jobs. Human output is a table with name, schedule, next fire, and the last run outcome/time when status is available. With owner auth, the CLI reads the live capsule status used by the dashboard; with only a deploy credential it still lists the schedules from deploy metadata.

`cloudbed cron run <name> [dir] [--api <url>] [--json]`

Trigger one scheduled job immediately through POST /v1/deploys/:id/crons/:name/run. Requires the same deploy credential as redeploys: owner auth, a deploy-scoped token, or the saved anonymous claim token. Human output prints ran <name>: ok and the returned result. Unknown names, suspended deploys, and handler failures surface as normal CLI errors with the platform error code.

`cloudbed push ls [dir] [--api <url>] [--json]`

Show a deploy's Web Push status through GET /v1/deploys/:id/push: saved subscription count, whether the capsule has VAPID keys, and whether sends are currently enabled. Requires the same deploy credential as redeploys.

`cloudbed push send [dir] [--title <t>] [--body <b>] [--url <u>] [--user <sub>] [--api <url>] [--json]`

Send a test notification through POST /v1/deploys/:id/push/send. --title defaults to Test notification; --body and --url are optional. Omit --user to broadcast to every subscription, or pass an auth subject to target that user's subscriptions. Human output prints sent, failed, and pruned counts.

`cloudbed releases [dir] [--json]`

List a deploy's release history, newest first: seq, created time, name, and a (current) marker. Every deploy (and rollback) appends a release; bundles are content-addressed, so history costs almost nothing. Requires the deploy credential (claim token from .cloudbed/deploy.json, or owner auth).

`cloudbed rollback [dir] [--to <seq>] [--json]`

Roll the deploy back to a previous release — by default the one just before the current, or an explicit --to <seq> from cloudbed releases. History is append-only: rolling back publishes a new release with the old content (like git revert), so you can roll forward again. Server env is not versioned and stays as-is. Deploys created before release history exists gain it on their next deploy.

`cloudbed delete [dir] [--yes] [--json]`

Permanently delete the deploy: wipes the capsule's database and stored files, frees the slug and any extra subdomains, removes release history, and garbage-collects unreferenced bundles. Prompts for confirmation on a TTY; non-interactive callers must pass --yes. Accepts the claim token or owner auth, and clears the local .cloudbed/deploy.json if it pointed at the deleted deploy.

`cloudbed usage [dir] [--days N] [--json]`

Read usage metering for the current deploy binding. Requires owner auth (cloudbed login or CLOUDBED_TOKEN) and defaults to the last 7 days, clamped by the API to 1–90 days. Human output shows totals plus per-day rows; --json prints the raw API response.

`cloudbed data-explorer [dir] [--port 4747] [--host <ip>] [--url <capsule-url>] [--token <inspect-token>] [--no-open]`

Open a local web page to browse a deployed capsule's data: table rows, stored files, logs, and the deploy manifest. Resolves the deploy and inspect token from .cloudbed/deploy.json (run from the app directory after cloudbed deploy) and serves the explorer on http://localhost:4747, opening your browser automatically (--no-open to skip).

The page talks only to the local server, which proxies to the capsule's private inspect routes — the inspect token never reaches the browser. The server binds to localhost unless --host says otherwise (e.g. a Tailscale IP to browse from another machine), and only answers requests addressed to the machine's own names — loopback, the bound address, its interface IPs, its hostname, or a *.ts.net MagicDNS name — which blocks DNS-rebinding attacks.

--url points the explorer at a capsule origin directly instead — for example --url http://localhost:3000 to browse a running cloudbed dev server (local inspect routes are open, so no token is needed), together with --token for a hosted capsule if you have its inspect token but no local deploy state.

Account

`cloudbed login [--token <token>]`

Authenticate the CLI. Without --token, this uses device flow: opens your browser, shows a confirmation code, and polls until you approve. With --token <token>, it validates the bearer token non-interactively. Saved credentials are written to ~/.cloudbed/auth.json.

`cloudbed logout`

Clear stored CLI credentials.

`cloudbed whoami [--json]`

Print the logged-in user as displayName (userId).

`CLOUDBED_TOKEN`

Set CLOUDBED_TOKEN to a bearer token for non-interactive auth. It is checked before ~/.cloudbed/auth.json and works for deploy, claim, whoami, token, domains, inspect, cron, push, and usage.

Tokens and domains

`cloudbed token create --name <name> [--deploy] [--json]`

Create an API token — personal by default, or scoped to the current directory's deploy with --deploy. The token value is printed once and never shown again.

`cloudbed token list [--json]`

List your tokens: id, name, and scope ([personal] or [deploy <id>]).

`cloudbed token revoke <id>`

Revoke a token by id.

`cloudbed domains add <hostname> [--json]`

Reserve an extra <name>.cloudbed.app subdomain for the current directory's deploy (labels are [a-z0-9-], 3–63 chars; some are reserved). Requires being the deploy's owner (or holding its claim token).