@cmd-deck/cli

Human-first CLI for cmd-deck.

Install

npm i -g @cmd-deck/cli

Human workflow

cmd-deck login
cmd-deck start
cmd-deck next
cmd-deck status
cmd-deck logout

• cmd-deck login defaults to OAuth.
• OAuth login requires pasting the full callback URL to verify state.
• Use cmd-deck login --api-key <key> to authenticate with an API key.
• Prefer cmd-deck login --api-key (without value) to avoid exposing keys in process args.
• cmd-deck next always checks notifications before picking the next task.

OAuth without an interactive prompt

The login can be split across two processes, which suits headless and agent-driven setups where nothing can block on stdin:

cmd-deck login --begin --json     # prints authorizeUrl + state, exits
# open authorizeUrl, approve, copy the callback URL from the address bar
cmd-deck login --callback-url "https://app.cmddeck.dev/oauth/callback?code=...&state=..."

The PKCE verifier is persisted to ~/.config/cmd-deck/pending-auth.json (0600) and matched against the state in the callback URL, so the second command can run minutes later, in a different shell. A positional URL works too (cmd-deck login "<callback url>"). Attempts are single-use and expire after 10 minutes.

Interactive cmd-deck login is otherwise as before, with one gain: because the attempt is persisted, you can interrupt it after approving in the browser and finish with --callback-url instead of starting over. An abandoned attempt leaves a verifier on disk until it expires, the next login supersedes it, or you run cmd-deck logout.

Note that --callback-url puts a single-use authorization code in your shell history and in ps output for the life of the command. It is short-lived and useless once exchanged, but on a shared machine prefer the interactive prompt, which reads the URL from stdin.

Themes

cmd-deck themes list
cmd-deck themes list --project <id>
cmd-deck themes create "Billing" --description "Payments work"
cmd-deck themes create "Billing" --project <id>

• --project is optional when the workspace has exactly one project; with several, the CLI lists them and asks you to pick.
• Creating a theme whose name already exists in the project returns the existing one rather than erroring.

Agent/automation mode

Use explicit commands and --json:

cmd-deck check-in --json
cmd-deck tasks list --json
cmd-deck notifications list --json
cmd-deck columns --json                 # board column ids + names
cmd-deck tools --json                    # every raw tool + JSON schema
cmd-deck tools move_card --json          # one tool's full schema
cmd-deck raw list_projects --json

Discovering raw tools

cmd-deck tools (alias: cmd-deck raw --list) lists every MCP tool the server exposes, with names, required args, and full JSON schemas — sourced live from the server so it can never drift. Pass a tool name for just that tool's schema.

Gotchas the tool list resolves:

• Tools are card-centric, not task-centric: create_card, list_cards, update_card, move_card, add_comment (there is no create_task/add_task).
• move_card targets a column by column_name ("In Progress", "Review", "Done") — run cmd-deck columns to see the valid names and ids.
• add_comment uses the field comment (not content).
• A typo'd raw tool errors with the closest matches and a pointer to cmd-deck tools.
• Agent tools need an agent_name; cmd-deck check-in auto-registers this workspace as an agent after cmd-deck login.

JSON output envelope:

{
  "ok": true,
  "command": "start",
  "data": {},
  "error": null
}