Install
Get started
Rundeck 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:
- Creates the organization on the Free plan and saves the API key in the CLI’s config file and your project’s env file.
- Links the project directory to the organization in
.deck/project.jsonand adds.deck/to your.gitignore, if you have one. - 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.
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 theclaim_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 runningdeck init:
--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 withdeck 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
Everycreate and update takes the full request body with --input, as inline JSON, a file, or stdin. Flags set top-level fields and override --input.
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:
--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:
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:
--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.