# `godmode-cli`
`godmode-cli` builds the `godmode` executable, a Rust-native task graph and development session
manager. It parses commands with Clap, resolves the active repository, delegates domain work to
`godmode-core`, and renders human-readable, JSON, or command-specific SARIF output.
The CLI is the workspace's user-facing process boundary. Domain state transitions, persistence,
policy evaluation, release logic, and external-tool adapters belong in `godmode-core`; command
modules under `src/commands/` own argument-to-API mapping and output behavior.
## Contents
- [Build And Install](#build-and-install)
- [Repository Resolution And Global Output](#repository-resolution-and-global-output)
- [Quick Start](#quick-start)
- [Command Reference](#command-reference)
- [Configuration And State](#configuration-and-state)
- [Development And Testing](#development-and-testing)
## Build And Install
From the workspace root:
```console
cargo build -p godmode-cli
cargo run -p godmode-cli -- --help
```
Build and install the release binary with the workspace task:
```console
cargo xtask install
godmode --version
```
`cargo xtask install` copies `target/release/godmode` (or the configured Cargo target directory)
to `$HOME/.cargo/bin/godmode`.
Generate Nushell completions:
```console
godmode completions > godmode.nu
```
Completion generation is handled before normal Clap parsing and writes the script to standard
output.
## Repository Resolution And Global Output
Commands start at the current directory, walk upward to the nearest `.git`, and otherwise use the
current directory. A `pinned_root` in `.ctx/godmode/session.json` overrides that detected root;
manage it with `godmode pin` and `godmode unpin`.
Global options may appear with any command:
| `--json` | Request machine-readable JSON from command handlers that support structured output |
| `--sarif` | Request SARIF v2.1.0 from verification and review commands |
| `-h`, `--help` | Print command help |
| `-V`, `--version` | Print the workspace package version |
Errors use `miette` diagnostics. Template errors retain their typed source labels and help text;
other errors are converted to reports with their context chain. `task next` and empty dispatch
results use exit code 2 to distinguish a successful empty result from an error (exit code 1).
## Quick Start
Create and execute a small dependency chain:
```console
godmode init
godmode task add "Write a failing test" --id t1 --crate-name godmode-core
godmode task add "Implement the behavior" --id t2 --depends-on t1 \
--crate-name godmode-core --run "cargo nextest run -p godmode-core"
godmode task next
godmode task start t1
godmode task done t1 --notes "Contract captured"
godmode task start t2
godmode task run t2 --auto-done
godmode status
```
The task graph is persisted at `.ctx/godmode/tasks.yaml`. `godmode init` creates the expected
global/project state directories and ensures `.ctx/` is ignored.
Ingest a plan generated by the writing-plans workflow:
```console
godmode plan ingest docs/plans/2026-05-02-godmode-verify-wave-worktree-ci.md
godmode dispatch --max 5
godmode visualize-graph --format dot --out .ctx/godmode/tasks.dot
```
Plan headings use `### Task N: Title`; optional `**Crate**`, `**Run**`, and `**Depends-on**`
annotations become task fields. Re-ingesting the same source is idempotent, while colliding plans
receive deterministic namespaced IDs.
## Command Reference
Run `godmode <command> --help` for complete argument and flag details.
### Sessions And Tasks
| `handon [--compact]` | Show session-start triage, running work, runnable work, and blocks |
| `handoff` | Warn about running tasks and emit session/handoff summaries |
| `status [--compact]` | Show graph counts and next runnable work |
| `context` | Emit repository, task, commit, critical-path, and Coursers context |
| `session prune --older-than N [--dry-run]` | Remove or preview old session JSONL files |
| `pin [PATH]`, `unpin` | Set or clear the repository root used by the session |
Task operations:
| `task list [--priority LEVEL] [--filter TEXT]` | List and filter tasks |
| `task next [--priority LEVEL]` | List pending tasks whose dependencies are done |
| `task add TITLE [options]` | Add a task and its execution metadata |
| `task start ID` | Validate dependencies and mark a pending task running |
| `task done ID [--commit SHA] [--notes TEXT]` | Complete a running task |
| `task block ID REASON` | Block a task and retain the reason in notes |
| `task unblock ID`, `task unblock-all` | Reset one or all blocked tasks to pending |
| `task run ID [--auto-done]` | Execute the task's `run` field through the Rx adapter |
| `task remove ID` | Remove a task and references to it |
| `task clear --done\|--all` | Remove completed tasks or the whole graph |
| `task pull [--project NAME]` | Import pending Doob work |
| `task pull --github [--repo OWNER/REPO] [--label LABEL]` | Import GitHub issues |
| `task push [--project NAME]`, `task push-done` | Publish local tasks or sync completions to Doob |
| `task apply NAME [--var KEY=VALUE]` | Resolve and apply a local/global task template |
| `task list-templates` | List discovered task templates |
Priorities are `high`, `normal`, and `low`. Repeat `--tag` to attach multiple tags. Omit
`--depends-on` for a root task; values are comma-delimited when supplied.
### Planning, Dispatch, And Parallel Work
| `plan ingest PATH` | Parse and atomically persist plan tasks |
| `dispatch [--max N]` | Emit independent active chains for parallel agents |
| `dispatch --critical-path` | Emit the longest active dependency chain |
| `agent dispatch PATH [--max N]` | Ingest a plan and emit its dispatch payload |
| `wave init --wave N --agents a,b` | Create persisted parallel-agent slot state |
| `wave status` | Show slot branches, statuses, and commits |
| `wave done AGENT [--commits a,b]` | Mark a slot complete |
| `wave block AGENT` | Mark a slot blocked |
| `wave check` | Fail while any slot remains pending |
| `worktree add BRANCH [--issue N]` | Create a linked worktree |
| `worktree remove BRANCH` | Remove a worktree after merge validation |
| `visualize-graph [--format dot\|svg] [--out PATH]` | Render the task graph |
### Agents, Skills, Hooks, And Policies
| `agent` | `list`, `index`, `dispatch`, `generate`, `migrate` |
| `skill` | `list`, `install PATH`, `uninstall NAME` |
| `hook` | `list`, `log [--tail N]`, `test SCRIPT`, `migrate`, `run NAME` |
| `policy` | `resolve AGENT [--level]`, `check AGENT TOOL`, `list`, `audit [--date]` |
| `review` | `self`, `skills`, `agents` |
Agent generation reads structured definitions from `agents/cfg/*.cfg.yaml` and prompt text from
`agents/prompts/`. The skill registry persists globally at
`$HOME/.config/godmode/registry.json`. Governance policies compose repository policy files and can
return allow, deny, or review decisions; policy audit events are stored under `.ctx/godmode/`.
### Pipelines And Workflows
| `pipeline list`, `pipeline show NAME` | Discover YAML skill pipelines and inspect steps |
| `pipeline start NAME [--from SKILL]` | Activate a pipeline at a valid entry point |
| `pipeline next`, `pipeline skip` | Advance the current step as done or skipped |
| `pipeline status`, `pipeline stop` | Inspect or clear active pipeline state |
| `pipeline run NAME [--from SKILL] [--fail-fast]` | Execute task-backed steps headlessly |
| `workflow list [--agent NAME]` | List workflow DAGs from agent definitions |
| `workflow run AGENT WORKFLOW` | Execute runnable command steps in dependency order |
| `workflow status NAME` | Inspect persisted workflow state |
Pipeline definitions live in `pipelines/*.yaml`; active state is stored in
`.ctx/godmode/pipeline.yaml`. Workflow state is stored as
`.ctx/godmode/workflow-<name>.json` and includes a definition hash for safe resumption.
### Quality, Evaluation, And Releases
| `verify [--crate-name NAME]` | Run quality gates and inspect recent commit history |
| `eval` | `run`, `compare`, `promote`, and `status` bounded skill evaluations |
| `release` | `current`, `bump [--version]`, `tag`, `push`, `changelog`, `validate` |
| `ci triage [--run-id ID]` | Fetch and classify a failed GitHub Actions run |
| `doctor` | Check required tools, 1Password authentication, and worktrees |
`eval run` consumes a skill's `evals/evals.json` plus a deterministic results fixture and enforces
repeat, case-count, and dollar-cost bounds. Stored runs and promoted baselines live under
`.ctx/godmode/evaluations/<skill>/`.
### Repository And Reporting Utilities
| `issue` | `list`, `close`, and preview/apply `sync-todos` |
| `graph build` | Construct a graph interactively or from YAML with `--var` substitutions |
| `memory-banking` | `inject`, `remind`, `init`, `status` |
| `insight` | `add`, `list [--date]`, `render [--date]` |
| `init` | Initialize global config and local state |
| `scaffold CRATE DIMENSION` | Generate a test module stub |
| `test-check PATH` | Check whether a Rust source file has associated tests |
Valid scaffold dimensions are `unit`, `property`, `fuzz`, `conformance`, `integration`, and
`regression`.
## Configuration And State
Configuration precedence is repository `.godmode.toml`, global
`$HOME/.config/godmode/config.toml`, then defaults. The TOML model contains an optional project
name, integration toggles (`doob`, `hj`, `crux`, `rx`, `crs`), and handoff settings.
Frequently used state paths:
| `.ctx/godmode/tasks.yaml` | Task graph and plan-import mappings |
| `.ctx/godmode/session.json` | Session metadata and optional pinned root |
| `.ctx/godmode/sessions/` | Task trace and session summary JSONL files |
| `.ctx/godmode/pipeline.yaml` | Active pipeline state |
| `.ctx/godmode/wave-status.json` | Parallel wave slots |
| `.ctx/godmode/reports/` | Generated report artifacts |
## Development And Testing
From the workspace root:
```console
cargo check -p godmode-cli
cargo clippy -p godmode-cli --all-targets -- -D warnings
cargo nextest run -p godmode-cli
cargo run -p godmode-cli -- --help
cargo run -p godmode-cli -- task --help
```
Command integration tests under `crates/godmode-cli/tests/` cover plan ingestion, Doob publishing,
pipeline entry points, task metadata and priority filtering, and graph visualization. For the full
workspace contract, including plugin structure and serialization behavior, run:
```console
cargo xtask ci
```
When adding a command, update the Clap enum and the corresponding module in `src/commands/`, route
it through `commands::dispatch`, support structured output where applicable, and add parser or
process-level coverage. Keep business rules in `godmode-core` rather than command handlers.