deck / project specs

CLI and AI agents

How to use deck non-interactively: command catalog, JSON output and rules for AI agents.

A CLI designed for scripts and agents

Every Deck command was designed to run with nobody watching: explicit flags instead of prompts, --json on queries and --yes on commands that change state. This applies to CI scripts, to team shortcuts and to AI agents such as Claude Code, which operate deck like any other command-line tool.

A single catalog

Commands are declared in one place (internal/commands/registry.go). The interactive menu, each command’s --help, the dispatch and the JSON catalog all come from that registry:

deck --help                 # commands grouped by category
deck boards-move-card --help
deck --schema               # full catalog as JSON (name, category, usage, flags)

--schema is the recommended way for an agent to discover what exists, instead of guessing names or reading the code.

Conventions

Convention	Example
Queries accept `--json`	`deck git-dashboard --json`, `deck boards-card-status --id 1234 --json`
State-changing commands accept `--yes`	`deck git-checkout-branch --branch dev --yes`
Flags as `--name value` or `--name=value`	`deck db query --sql="select 1" -p local`
`--` ends the flags	what follows is positional, even if it starts with `-`
Non-zero exit code on error	scripts can rely on `$?`
`deck` with no arguments opens the interactive menu	requires a terminal; do not use it from an agent

Rules for AI agents

These rules are in the repository’s CLAUDE.md and apply to any agent:

Discover commands and flags with deck --schema; pass every required flag.
Never use the interactive menu (deck with no arguments).
Move cards only through the CLI helper: deck boards-move-card --id N --state "<phase>". It resolves the board column to the correct System.State; writing the column name directly into System.State returns HTTP 400 and System.BoardColumn is read-only.
With no associated card, use the id 00000: the CLI does not call the board API or prefix commits and PRs with AB#.
Secrets are stored with deck secrets set <NAME>, which reads the value from stdin, never from the command line (where it would end up in the shell history and the process list).

Examples

Start a task, commit and open the PR, from the terminal or through an agent:

deck git-workflow-start-dev --mode buscar-tarefa --card 4321 --repo web --slug tela-login --yes
# ... changes ...
deck git-smart-commit --repo web --msg "feat: login screen" --push
deck git-workflow-code-review --repo web --title "Login screen" --yes

Investigate an incident:

deck logs-search --env dev --app api --level ERROR --query-text "timeout" --tail 200
deck db run pedidos-travados -p hml --param status=PENDENTE --json
deck azure-pipelines logs api        # failed step of the last run

Run an E2E test against staging:

deck tests list                      # each .spec file becomes an ID: login.spec.ts → LOGIN
deck tests run LOGIN --env hml
deck tests history

Updating the CLI

deck updates itself in the background (at most one check every 15 minutes), without making any command wait on the network. The controls are in the command itself and on the panel’s /cli screen:

deck update --status          # version, channel and automatic update status
deck update                   # update now
deck update --canal dev       # follow development versions
deck update --rollback        # go back to the previous version
deck update --auto off        # turn off automatic updates

Every update is verified before the swap: release signature, binary checksum and a test run of the new version. Details in Security.