# 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:

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

The command exits nonzero. Branch on `error.code`; see [Deploying with an agent](/agents#error-handling) for the code table.

## 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 init [dir] [--template todo|guestbook] [--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] [--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](/deploys)) 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 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.

With `--json`, the response includes `deployId`, `url`, `name`, `mode`,
`claimed`, `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](/deploys).

### `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.

## 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`, and `inspect`.

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