Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · Interfaces

Command line reference

On this page
  1. Synopsis
  2. gitoodo next
  3. gitoodo done
  4. gitoodo status
  5. gitoodo doctor
  6. gitoodo trace
  7. gitoodo diagnose
  8. gitoodo token-access
  9. gitoodo token-purge
  10. gitoodo release
  11. gitoodo service
  12. gitoodo --version
  13. gitoodo classifier
  14. gitoodo daemon
  15. gitoodo dispatcher
  16. gitoodo ask
  17. gitoodo worker context
  18. gitoodo worker push
  19. gitoodo worker follow-up
  20. gitoodo hook
  21. gitoodo satellite
  22. gitoodo host add
  23. gitoodo labels migrate
  24. gitoodo attach
  25. gitoodo mcp

Every subcommand of the gitoodo command line, generated from the text gitoodo --help prints (the USAGE constant in crates/cli/src/main.rs). The app installs the command with its background services; the daemon reference covers configuration and tokens.

Synopsis#

usage:
  gitoodo next --worker <id> --host <host> [--repo <owner/name>] [--account <id>] [--json]
  gitoodo done --worker <id> --lease <id> [--result <text>] [--json]
  gitoodo status [--changed] [--json] [--ack]
      queue picture of all configured accounts
      --changed  exit 0 when the waking lines changed since the last --ack, 1 otherwise
      --json     machine-readable output
      --ack      remember the current waking lines as seen
  gitoodo doctor
      diagnostics: where the daemon takes tokens from (systemd credentials, service environment, system keyring or memory only)
  gitoodo trace <owner/repo#n | run-id> [--local] [--output]
      timeline of one issue or run from the logs: every step from the classifier's decision over
      host choice, worktree, worker, pull request and checks to merge and cleanup, with durations;
      also asks the satellites for their lines (--local: this machine only); read-only, redacted;
      names the worker transcripts kept on this machine (--output: prints them)
  gitoodo diagnose [--hours <n>]
      summary of the last 24 hours (or n): runs, count and p50/p95 per step, top wait reasons,
      errors by kind, the log folder against its budget and the cleanup state (leftover worktrees
      and branches, disk, errors); read-only, redacted
  gitoodo token-access --account <id> [--grant]
      whether the background services read the account's token without a keychain prompt; prints
      readable, needsPrompt, missing or failed; --grant asks once so "Always Allow" can be chosen
  gitoodo token-purge
      remove every Gitoodo token from the data protection keychain (the uninstaller runs it through
      the service helper, which shares the app's keychain group); prints removed or unavailable
  gitoodo release [--repo <owner/name>] [--json]
      release planning: open, in-progress and merged items of the next release (docs/orchestrator/release.md)
  gitoodo service install|uninstall|start|stop [classifier|dispatcher|all]
      background services with the system service manager (restart on crash and reboot);
      default classifier; install copies this CLI to a stable per-user folder first
  gitoodo --version
      print the CLI version (the app compares it with its own)
  gitoodo classifier
      run the classifier daemon in the foreground (what the service starts)
  gitoodo daemon
      deprecated alias of `gitoodo classifier`
  gitoodo dispatcher
      run the dispatcher in the foreground: one Claude worker per ready issue (docs/orchestrator/dispatcher.md)
  gitoodo ask [--issue <key>]
      worker: post a question block (JSON spec on stdin) to the issue and wait for a human
  gitoodo worker context
      print compact assigned issue context as JSON; requires GITOODO_ISSUE (local workers only)
  gitoodo worker push | pr [--title <t>] [--body <text>]
      worker: push the branch and open the pull request that closes the issue, through the account
      connected in Gitoodo (the worker never holds a token)
  gitoodo worker follow-up --title <t> --body-file <path|-> [--label <kind>]
      worker: propose a follow-up issue for work outside the own issue; the dispatcher creates it
      with a back-reference, and a maintainer approves it before a worker picks it up
  gitoodo hook status-line|stop|stop-failure
      Claude hook ping to the dispatcher (silent without one)
  gitoodo satellite [--stdio]
      remote host service for workers (docs/orchestrator/satellites.md); --stdio is the SSH bridge
  gitoodo host add <name> <ssh-target> | list | remove <name>
      configure satellites (ssh target only, no secrets)
  gitoodo labels migrate <account> <owner/repo> [--yes]
      switch an active repo from legacy label names to the catalog by renaming (issues keep their
      labels); prints the preview and changes nothing without --yes
  gitoodo attach [--host <name>] <issue>
      terminal of a worker, raw mode, detach with Ctrl-]; the worker keeps running
  gitoodo mcp [--scope all|<account>/<owner>/<name>[#<n>]]
      MCP server over stdio: the ledger and the dispatcher as read tools plus change proposals
      that wait for the human's OK (docs/orchestrator/chat.md); --scope narrows them to one
      repository or item

gitoodo next#

gitoodo next --worker <id> --host <host> [--repo <owner/name>] [--account <id>] [--json]

gitoodo done#

gitoodo done --worker <id> --lease <id> [--result <text>] [--json]

gitoodo status#

gitoodo status [--changed] [--json] [--ack]

queue picture of all configured accounts --changed exit 0 when the waking lines changed since the last --ack, 1 otherwise --json machine-readable output --ack remember the current waking lines as seen

gitoodo doctor#

gitoodo doctor

diagnostics: where the daemon takes tokens from (systemd credentials, service environment, system keyring or memory only)

gitoodo trace#

gitoodo trace <owner/repo#n | run-id> [--local] [--output]

timeline of one issue or run from the logs: every step from the classifier's decision over host choice, worktree, worker, pull request and checks to merge and cleanup, with durations; also asks the satellites for their lines (--local: this machine only); read-only, redacted; names the worker transcripts kept on this machine (--output: prints them)

gitoodo diagnose#

gitoodo diagnose [--hours <n>]

summary of the last 24 hours (or n): runs, count and p50/p95 per step, top wait reasons, errors by kind, the log folder against its budget and the cleanup state (leftover worktrees and branches, disk, errors); read-only, redacted

gitoodo token-access#

gitoodo token-access --account <id> [--grant]

whether the background services read the account's token without a keychain prompt; prints readable, needsPrompt, missing or failed; --grant asks once so "Always Allow" can be chosen

gitoodo token-purge#

gitoodo token-purge

remove every Gitoodo token from the data protection keychain (the uninstaller runs it through the service helper, which shares the app's keychain group); prints removed or unavailable

gitoodo release#

gitoodo release [--repo <owner/name>] [--json]

release planning: open, in-progress and merged items of the next release (docs/orchestrator/release.md)

gitoodo service#

gitoodo service install|uninstall|start|stop [classifier|dispatcher|all]

background services with the system service manager (restart on crash and reboot); default classifier; install copies this CLI to a stable per-user folder first

gitoodo --version#

gitoodo --version

print the CLI version (the app compares it with its own)

gitoodo classifier#

gitoodo classifier

run the classifier daemon in the foreground (what the service starts)

gitoodo daemon#

gitoodo daemon

deprecated alias of gitoodo classifier

gitoodo dispatcher#

gitoodo dispatcher

run the dispatcher in the foreground: one Claude worker per ready issue (docs/orchestrator/dispatcher.md)

gitoodo ask#

gitoodo ask [--issue <key>]

worker: post a question block (JSON spec on stdin) to the issue and wait for a human

gitoodo worker context#

gitoodo worker context

print compact assigned issue context as JSON; requires GITOODO_ISSUE (local workers only)

gitoodo worker push#

gitoodo worker push | pr [--title <t>] [--body <text>]

worker: push the branch and open the pull request that closes the issue, through the account connected in Gitoodo (the worker never holds a token)

gitoodo worker follow-up#

gitoodo worker follow-up --title <t> --body-file <path|-> [--label <kind>]

worker: propose a follow-up issue for work outside the own issue; the dispatcher creates it with a back-reference, and a maintainer approves it before a worker picks it up

gitoodo hook#

gitoodo hook status-line|stop|stop-failure

Claude hook ping to the dispatcher (silent without one)

gitoodo satellite#

gitoodo satellite [--stdio]

remote host service for workers (docs/orchestrator/satellites.md); --stdio is the SSH bridge

gitoodo host add#

gitoodo host add <name> <ssh-target> | list | remove <name>

configure satellites (ssh target only, no secrets)

gitoodo labels migrate#

gitoodo labels migrate <account> <owner/repo> [--yes]

switch an active repo from legacy label names to the catalog by renaming (issues keep their labels); prints the preview and changes nothing without --yes

gitoodo attach#

gitoodo attach [--host <name>] <issue>

terminal of a worker, raw mode, detach with Ctrl-]; the worker keeps running

gitoodo mcp#

gitoodo mcp [--scope all|<account>/<owner>/<name>[#<n>]]

MCP server over stdio: the ledger and the dispatcher as read tools plus change proposals that wait for the human's OK (docs/orchestrator/chat.md); --scope narrows them to one repository or item

Docs version: dev