CLI reference

Commands are nouns with verbs: devplane run show, devplane inbox answer. Plain devplane runs devplane status. A verb typed without its noun (devplane connect) is refused, naming the right command.

• --json works on every command, before or after its name. A failure is {"error": "…"} on stdout with a non-zero exit. It changes nothing for run watch, run attach, gate install, completions and up.
• Colour follows NO_COLOR and is off when output is not a terminal; CLICOLOR_FORCE=1 forces it.
• Reading needs no host. status, run list, run show, inbox, audit, search, change list, change show and agent list read the store when no host answers, and say what only a host sees. Starting, steering or stopping an agent needs the host. inbox answer works without one.
• Exit codes: 0 success, 1 failure, 2 a usage error, 3 a refusal by change draft or change offer. devplane verify and devplane gate have their own.

Naming a run, a change or an ask

Every id takes the full id or any unique prefix; a run also takes its session name.

$ devplane status
core-lib
  ● a1         vscode     88%   $0.41   2s  Bash: cargo test --workspace

$ devplane run show a1

An ambiguous prefix is an error listing the matches; a live session wins over one that never reported. change prompt, change stop and inbox snooze take a change or a run.

The groups

devplane --help lists the commands under five groups:

Hidden, for machines: devplane mcp (below), and devplane hook and devplane statusline, which devplane agent connect installs.

See what is happening

devplane status

Sessions in play, and anything asking for you.

devplane run

run watch flags: --thinking includes the agent’s reasoning where streamed; --history <n> is how much conversation to print first (default 40).

devplane search <query>

Full-text search over tool calls, questions and errors in every session. The query is a phrase.

What needs you, and what happened without you

devplane inbox

What needs a person, by band, then oldest first. Derived from state, so correct after a restart.

$ devplane inbox
since you last looked · 16h

 ! Keep the legacy /v1/login route? [question] saas 3m new
   Gate failed after the agent claimed completion [gate_failed] core-lib 5h

• new marks what arrived since you last read the inbox. An empty inbox counts the decisions taken in your name and by whom.
• A narrowed list counts what it hides. Filters are not remembered.
• Above twelve rows, issues and stalled sessions fold into a counted row. Questions, permissions and drift never fold.
• A permission item names the narrowest rule that would stop the ask. Nothing is written for you.
• gate_down: the permission gate is not answering. config_broken: a devplane.toml will not load.

--all lists open asks first, then settled ones with what ended them: you, a clock ([questions] deadline) or nobody, then questions an agent moved past.

devplane inbox answer <ask>

Answer a permission or a question by the id devplane inbox prints. The id outlives the asking process; a late answer reaches the agent through a resumed session.

• One of --allow, --deny, --option or --custom is required.
• --allow, and --option without --field, are refused inside an agent session (Security).
• There is no dismiss. The first answer wins; a second is told who gave the first.

devplane inbox snooze <id>

Hide a run’s or a change’s current inbox items for a while; new kinds still show, and the run keeps running. A question or a permission is never snoozed. devplane inbox counts what is snoozed.

devplane audit [about]

What Devplane decided, and on whose authority: person, rule, timer, nobody or devplane. about narrows to one run or change. How to read it: the decision log.

An MCP tool call’s row says where its server was defined (project, user, plugin, sdk), or that it was not reported.

devplane pr list and devplane issue list

Open pull requests and issues across registered projects, read with your GitHub sign-in, what needs you first. Alias ls. Nothing is written to GitHub.

• The host refreshes them every five minutes and after a sign-in.
• Each project shows its GitHub state (not signed in, expired, rate limited, unreachable, stale, not a GitHub repository) and how many are open past the page read.
• In pr list, ◆ marks what waits on you: a review requested of you, or your own pull request that is red, has changes requested, or is approved and unmerged.

Start and steer work

devplane change

A change is an isolated checkout, an agent in it, and [gates] check run when the agent finishes. Its states are drafted, isolated, in flight, verified, offered and archived (Verified done). Every <change> is an id or unique prefix as change list prints it.

Refused inside an agent session: change resume, login, claim-read, draft, draft-accept, draft-reject, offer, and review --seen.

devplane change start [title]...

devplane change start "add rate limiting to /login"
devplane change start --spec specs/001-password-reset --task REQ-3 "password reset"
devplane change start --project api --project web "bump tokio to 1.40"

The title is the first prompt and, slugged, the branch (change/add-rate-limiting-to-login-3f9a1c).

Every project is checked first (trusted, clean, readable devplane.toml, matching --task); one refusal starts none. The preflight names [workspace] setup, or warns of a lockfile without one.

Reading a change

tasks      11 ticked · 9 seen by a passing check
REQ-3      3 tasks · 2 ticked · 0 seen by a passing check
drift      the specification changed 18m into run r-9f2 and the run never saw it
           devplane change drift c-01a0 --run r-9f2 --accept | --tell

change review flags:

change export flags and exits:

Exit 1, writing nothing, when the change has no statement (no check run, no tree recorded), when signing fails, or when --out exists. Exit 2 for --sign without --out.

devplane change export c-01a0 > cert.md
devplane change export c-01a0 --sign ssh --out c-01a0.intoto.json

Steering a change

Drafting a specification

change draft flags: --agent <id>, --methodology speckit|openspec (needed only where the project has both), --project <name|path>, --change <change> (draft again into a change whose draft was rejected), --dry-run (print what would be sent). Accept and reject are refused while the agent is mid-turn. Full rules: Specifications.

Ending a change

change offer is refused with exit 3 while a weakened row is unseen (--json: refused, rows, seen_with), and when the tree moved since the last pass (rules).

devplane gate

Run this repository’s gates and report the exit codes. No host, no record, no spec. A Spec Kit hook or a verify skill calls it.

--json also prints passed, summary and commands.

devplane gate install

Put the gate where a workflow runs it. One of --speckit or --skill is required. Refused while the repository declares no gate. Setup: Specifications and Driving agents.

devplane verify

Run the base’s check on this change, leading with the checks it weakened. For CI (CI verify) or before you push. Needs only git: no host, store or network unless --approvals is passed.

• The change is the diff from the merge base with --base to the working tree, untracked files included.
• check, its timeout and review roles come from devplane.toml at the merge base. A change that edits check is judged by the base’s, and the edit is the summary’s first row.

Weakened checks never change the exit code. --json prints one document: verdict, exit, base, tree, weakened rows and each command’s outcome. Under GitHub Actions, weakened rows and failing named tests are also annotations.

Set up a project

devplane project trust [path]

Allow agents in a repository (default: here), after printing the hooks and MCP servers an agent would load there:

$ devplane project trust .
  starting an agent here loads this repository's own:

  hook    ./scripts/guard.sh
          runs on every PreToolUse in this repository
  mcp     notes
          `notes-mcp` has no version pin, so starting an agent fetches and
          runs whatever is published at that name today

  Trust this repository? [y/N]

Refused inside an agent session. It writes ~/.devplane/trusted.toml and has a running host re-read it.

devplane config

Read devplane.toml, ask what its rules decide, and manage your grants. Offline.

$ devplane config explain 'git push --force origin main'
ask  Bash
        by Bash(git push *)

$ devplane config explain 'rm$IFS-rf node_modules'
ask — unreadable  Bash
        because the program is named by a variable the shell expands; …

$ devplane config explain 'cargo test'
undecided  Bash
        its rules loaded and none answers this one, so the provider's own dialog decides and it reaches your inbox

explain verdicts are deny, ask, ask — unreadable (unresolved in --json), undecided, or allow only for your own grant. See Permissions.

devplane agent

• Both show the diff and ask on a terminal. Elsewhere, and under --json, they write only with -y.
• Hooks run the binary by full path, so a temporary binary is refused (npx’s cache, macOS App Translocation, /Volumes, an AppImage mount). Run connect again after moving or reinstalling.
• Codex runs a hook only after you approve it in its own dialog. For Copilot, connect prints three environment lines to export. See Watching sessions.

devplane auth

gh auth token | devplane auth login --with-token  # GitHub CLI's token
devplane auth login --with-token < pat.txt        # a fine-grained personal access token

login --json prints { "state": "pending", "user_code", "verification_uri", "expires_at" }, then { "host", "login", "scopes" }. A build’s own OAuth app covers github.com only; an Enterprise app is set per host in app.toml.

devplane doctor

Whether Devplane works on this machine. The probe is recorded nowhere.

devplane completions <shell>

bash, zsh or fish. Ids complete from a running host or the store, never starting one.

devplane completions zsh  > ~/.zsh/completions/_devplane
devplane completions bash > /etc/bash_completion.d/devplane
devplane completions fish > ~/.config/fish/completions/devplane.fish

See Install.

devplane mcp

Hidden. Devplane over MCP on stdio: four questions and one claim. The plugin registers it, and every agent Devplane drives is offered it. By hand:

{ "mcpServers": { "devplane": { "command": "devplane", "args": ["mcp"] } } }

The questions ask a host, else read the store, and act on nothing.

spec_and_tests_conflict takes exactly reason (1 to 1024 bytes) and paths (at most 10, each at most 512 bytes, inside the project or the change’s worktree). The run, change and a per-session key come from the server’s environment, and the host checks them. Anything else (a session Devplane did not start, no host, another run’s server, a second open claim, an argument out of bounds) is refused with a sentence and nothing recorded. Devplane never allows the call itself.

The host

The one long-lived process (Architecture). Nothing starts it automatically.

devplane up

Start the host and open the workbench. With a host running, only open it; otherwise this process is the host until ctrl-c.

A port held by another process is refused, naming the holder (Troubleshooting). A second host on the same home is refused with the running one’s port and uptime.

devplane up --window

The host with a native window: a tray item with the need you count, notifications, one global shortcut ([app] shortcut), and devplane:// links to a change, review, ask or run. Closing the window keeps hosting; quitting from the tray says what it stops. Nothing starts at login. Needs a build with the app feature (cargo install devplane --features app); otherwise the flag is hidden and refused.

devplane down

Stop the host, first saying what ends: driven agents stop; your own sessions and waiting questions stay.

Quitting stops 2 agents Devplane started:
  r-4f2a9c1e  claude  ~/code/api
  r-8b31d07a  gemini  ~/code/web
It leaves 3 sessions running in their own terminals untouched.
Stopped.

Stopped. prints once the port is quiet. With no host: Nothing is running.

Something wrong or out of date? Edit this page.