> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deck.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Deck CLI

> Set up, build, and run Deck agents from your terminal or a coding agent.

The Deck CLI covers the full [Deck API](https://docs.deck.co/api/using-the-api.md) from the terminal. It doesn't prompt for input, prints JSON, and its errors list the commands that fix them. It also ships a local version of the [Deck MCP server](https://docs.deck.co/mcp-server.md).

## Install

```bash theme={null}
npx @deckco/cli init
```

Or install it globally:

```bash theme={null}
npm install -g @deckco/cli
```

The CLI needs Node.js 20.11 or later.

## Get started

Run `deck init` in your project. If no Deck credentials are present, it creates a new organization with a working API key, so you can start building before anyone signs up.

```bash theme={null}
deck init
```

```json theme={null}
{
  "organization": { "id": "org_9f8e7d...", "name": "my-app", "claimed": false, "expires_at": "2026-11-24T21:42:31Z" },
  "api_key": { "prefix": "sk_live_1a2b3c4d", "file": "/path/to/my-app/.env.local", "config": "/path/to/config/deck/config.json" },
  "claim_url": "https://console.deck.co/claim?token=...",
  "steps": [{ "what": "mcp clients", "target": "every agent client on this machine", "outcome": "created", "detail": "installed into Cursor" }],
  "telemetry": { "status": "on", "detail": "command names and outcomes, never arguments", "turn_off": "deck telemetry disable" },
  "next_step": "Task runs need a claimed organization. Send claim_url to a human."
}
```

`deck init` does the following:

1. Creates the organization on the Free plan and saves the API key in the CLI's config file and your project's env file.
2. Links the project directory to the organization in `.deck/project.json` and adds `.deck/` to your `.gitignore`, if you have one.
3. Adds the local [MCP server](https://docs.deck.co/mcp-server.md) to the agent clients it finds: Claude Code, Claude Desktop, Cursor, and Windsurf. For Codex and VS Code, it prints the entry to paste.

It prints its plan before writing anything and a summary at the end. If a step fails, such as writing one client's config, it reports the step and the command to finish it, and carries on with the rest.

### Claim the organization

A new organization can create agents, tasks, and event destinations, but it can't add sources or run anything until a person claims it. Open the `claim_url` in a browser and sign in to Deck. You become the organization's Admin.

Until then, creating a source, task runs, workflow runs, and sessions return an `organization_unclaimed` error, and triggers don't fire. `deck init` also saves `claim_url` in `.deck/project.json`, and `deck agent-guide` prints it. After the claim, triggers start at their next scheduled time. Missed runs aren't backfilled.

An unclaimed organization expires seven days after it's created. `deck whoami` reports `claimed` and `expires_at`. To create a new organization, run `deck init --fresh`.

> [!NOTE]
>
> If you're a coding agent, send `claim_url` to the person you're working for. Keep building while you wait.

## Authenticate

The CLI looks for credentials in this order:

| Source | Use it for |
| - | - |
| `--api-key` flag | One-off commands |
| `DECK_API_KEY` environment variable | CI and scripts |
| `deck login` | Developers with a Deck account |
| The config file `deck init` wrote | Projects set up with `deck init` |

### Sign in

If you already have a Deck account, sign in instead of running `deck init`:

```bash theme={null}
deck login
```

It prints a sign-in page and a code, and opens the page in your browser when run in a terminal. After you sign in and approve the code, finish with:

```bash theme={null}
deck login --complete
```

The CLI then acts as you, with the permissions of your [role](https://docs.deck.co/guides/account/roles-and-permissions.md). It keeps the sign-in in your OS keychain when one is available.

If you belong to more than one organization, `--complete` lists them and the command to pick one. To change organizations later, run `deck orgs list`, then `deck orgs switch <clerk_org_id>`.

A coding agent sends the sign-in URL from `deck login` to the person it's working for, then runs `deck login --complete` after they sign in. Until they do, it returns `login_pending`.

`deck logout` removes the sign-in from this machine. It leaves any API key in place.

### API keys for CI

Create a key for CI with `deck keys create`, then set it as `DECK_API_KEY`. The secret is printed once and not stored. An API key acts as an Admin of its organization.

```bash theme={null}
deck keys create --name ci
```

`deck keys list` and `deck keys retrieve` show existing keys, and `deck keys delete` revokes one.

### Check your setup

`deck whoami` reports which credential is in use, where it came from, and the organization commands act on, including whether it's claimed. `deck doctor` checks your credential, the project link, `.gitignore`, the MCP setup, and the CLI version, and returns the command that fixes each problem. `deck doctor --fix` applies the fixes that don't need a person.

Commands always act on the organization of the active credential. To record which organization a directory belongs to, run `deck link <org_id>`. `deck whoami` and `deck doctor` then warn when the active credential belongs to a different one. `deck unlink` removes the link.

## Commands

Each API operation has a command named for its resource and the verb in the [API reference](https://docs.deck.co/api-reference): `list`, `retrieve`, `create`, `update`, `delete`, plus actions like `run`, `cancel`, and `reset`.

```bash theme={null}
deck agents list
deck tasks retrieve task_a1b2c3d4...
deck task-runs cancel trun_a1b2c3d4...
```

`deck retrieve <id>` fetches any resource by its [ID prefix](https://docs.deck.co/api/resource-ids.md), so you don't need to know the resource type.

Run `deck <command> --help` for a command's flags, or `deck <command> --help --json` for the flag schema.

### Request bodies

Every `create` and `update` takes the full request body with `--input`, as inline JSON, a file, or stdin. Flags set top-level fields and override `--input`.

```bash theme={null}
deck agents create --input '{"name": "Hotel Reservations"}'
deck tasks create --input @task.json
cat task.json | deck tasks create --input -
```

The CLI checks flags and bodies against the API schema before sending and reports every problem at once, including unknown fields with a suggestion, and doesn't send an invalid request.

### Global flags

| Flag | Effect |
| - | - |
| `--dry-run` | Prints the request without sending it |
| `--yes` | Confirms a destructive command, such as `delete` |
| `--all` | Follows pagination to the end and prints one JSON object per line |
| `--limit`, `--cursor` | Paginates a list. See [Pagination](https://docs.deck.co/api/pagination.md) |
| `--fields <a,b.c>` | Keeps only the named fields |
| `--jq <expr>` | Applies a jq expression to the output |
| `--idempotency-key <key>` | Sets the [idempotency key](https://docs.deck.co/api/idempotency.md) on a write |
| `--verbose` | Prints request and response headers and the request ID to stderr |
| `--no-retry` | Turns off retries for rate limits and server errors |

List filters from the API are flags with the same names, such as `--source-id`. Date filters also accept relative values like `-7d` or `yesterday`.

### Any endpoint

`deck api` sends any request with your CLI credentials, including endpoints released after your CLI version:

```bash theme={null}
deck api GET /v2/agents
deck api ls
```

`deck api ls` lists every operation the CLI knows about.

## Output and errors

The CLI prints the API response body unchanged, as JSON.

Errors go to stderr in the same [error format](https://docs.deck.co/api/errors.md) as the API. `deck whoami`, `deck doctor`, `deck orgs list`, `deck feedback`, and `deck upgrade` are the exception: they print their report to stdout and exit non-zero when it's a failure. Errors from the CLI itself, such as a missing flag, have `type` set to `cli` and add `next_steps`, the commands that fix the problem in order.

| Exit code | Meaning |
| - | - |
| `0` | Success |
| `1` | The API or the CLI returned an error |
| `2` | Invalid usage, or a destructive command without `--yes` |
| `3` | No credentials found, or `deck login --complete` is still pending |

The CLI retries rate limits and server errors with backoff. Writes without an idempotency key aren't retried on server errors.

## Run tasks

`--wait` runs a task and returns the finished run:

```bash theme={null}
deck tasks run task_a1b2c3d4... --wait --input '{
  "credential_id": "cred_a1b2c3d4...",
  "input": { "check_in_date": "2026-04-01" }
}'
```

If the run needs an [interaction](https://docs.deck.co/guides/interactions.md), such as an MFA code, the command returns as soon as the run is waiting. Answer it, then keep waiting:

```bash theme={null}
deck task-runs interaction trun_a1b2c3d4... --input '{"input": {"code": "123456"}}'
deck task-runs watch trun_a1b2c3d4...
```

`--timeout <seconds>` caps the wait, which defaults to 300 seconds. If the wait times out, the command prints the run as it stands; run `deck task-runs watch` to keep waiting. `task-runs rerun`, `workflows run`, and `workflow-runs rerun` also take `--wait`.

To debug a failed run, fetch its screenshots and browser logs:

```bash theme={null}
deck task-runs screenshots trun_a1b2c3d4... --download ./screenshots
deck task-runs browser-logs trun_a1b2c3d4... --type console,network
```

For [sensitive tasks](https://docs.deck.co/concepts/tasks.md#sensitive-tasks), the CLI doesn't fetch screenshots or browser logs, or download stored files, matching the Console.

## Add credentials

The CLI never takes a password or other secret as a flag. `deck credentials create` accepts `auth_credentials` only in the request body, from a file or stdin:

```bash theme={null}
deck credentials create --input @credential.json
```

Use this for your own credentials or in CI. Don't give a coding agent someone else's password.

To collect credentials from someone else, create a credential link. The account holder enters their credentials on a page hosted by Deck, and the CLI waits for the new credential and prints it:

```bash theme={null}
deck credentials create --link --source-id src_a1b2c3d4...
```

The link is valid for up to 24 hours. `--timeout <seconds>` caps the wait, which defaults to 600 seconds; the link stays valid after the wait ends. Outside a terminal, `--link` needs `--yes`, so the link isn't recorded in an agent's transcript by accident. Coding agents should call `create_credential_link` on the hosted [Deck MCP server](https://docs.deck.co/mcp-server.md#credentials) instead, which returns a link that expires within an hour.

## Set up your coding agent

`deck init` registers the local MCP server for you. To do it separately, such as after `deck login` or installing a new client:

```bash theme={null}
deck agent setup
```

`deck agent setup` registers the local [MCP server](https://docs.deck.co/mcp-server.md) in the clients it finds and adds a section on using the Deck CLI to your project's `AGENTS.md`. Re-running it replaces the section. `deck mcp install` registers only the MCP server. `deck mcp list` shows which clients have it, and `deck mcp uninstall` removes it.

`deck agent-guide` prints, as one JSON object, what an agent needs on first contact: every command, the output and error contract, which credential is active, and the next step for the current state.

## Environment variables

| Variable | Effect |
| - | - |
| `DECK_API_KEY` | API key to use |
| `DECK_API_URL` | Overrides the API base URL |
| `DECK_CONFIG_DIR` | Overrides where the CLI stores its config |

## More commands

| Command | What it does |
| - | - |
| `deck version` | Prints the CLI version |
| `deck upgrade` | Updates the CLI (`--check` only reports) |
| `deck changelog` | Prints Deck changelog entries since your CLI version |
| `deck open <id>` | Prints the Console URL for a resource |
| `deck docs search <query>`, `deck docs read <page>` | Searches and reads these docs |
| `deck events verify --delivery <file>` | Checks a captured delivery's [signature](https://docs.deck.co/events/webhook-best-practices.md#verify-signatures), with the secret from `DECK_WEBHOOK_SECRET`, `--secret-file`, or `--secret-stdin` |
| `deck telemetry disable` | Turns off the CLI's usage analytics, which record command names and outcomes, never arguments |
| `deck feedback <message>` | Sends feedback to the Deck team |
| `deck completion <shell>` | Prints a shell completion script |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.