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.

Project

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

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.

`cloudbed dev [dir] [--port 3000] [--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.

`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] [--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 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.

Re-running deploy updates the existing deploy in place.

`cloudbed claim [dir]`

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 run against a local dev platform (--api http://localhost:…) with an inspect token, it also lists the deployed queries: and mutations:.

Account

`cloudbed login`

Authenticate the CLI via device flow: opens your browser, shows a confirmation code, and polls until you approve. The token is saved to .cloudbed/profile.json.

`cloudbed logout`

Clear stored CLI credentials.

`cloudbed whoami [--json]`

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

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).