Skip to main content
The Deck CLI covers the full Deck API 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.

Install

Or install it globally:
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.
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 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.
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:

Sign in

If you already have a Deck account, sign in instead of running deck init:
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:
The CLI then acts as you, with the permissions of your role. 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.
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: list, retrieve, create, update, delete, plus actions like run, cancel, and reset.
deck retrieve <id> fetches any resource by its ID prefix, 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.
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

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:
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 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. 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:
If the run needs an interaction, such as an MFA code, the command returns as soon as the run is waiting. Answer it, then keep waiting:
--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:
For 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:
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:
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 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:
deck agent setup registers the local MCP server 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

More commands