CLI Reference

Every dgov command and flag, grouped by purpose.

Overview

Bootstrap

dgov init

Scaffold .dgov/project.toml, .dgov/governor.md, and .dgov/sops/*.md. Auto-detects language, source directory, test directory, and toolchain.

dgov init
dgov init --force
dgov init --project-type python
dgov init --preflight

dgov init is idempotent for missing files: re-running it scaffolds whatever is missing without overwriting existing project config.

If sentrux is installed and .sentrux/baseline.json does not exist, dgov init offers to run dgov sentrux gate-save immediately.

Detected fields written to [project]:

• language, src_dir, test_dir, source_extensions
• test_cmd, lint_cmd, format_cmd, lint_fix_cmd, format_check_cmd
• [project].provider and [providers.<name>] entries
• coverage_cmd, coverage_threshold
• [tool_policy] defaults
• [scope] ignore_files seeded from detected lockfiles

See LLM Providers for provider variations.

dgov agents sync

Install or refresh the dgov-maintained skills in a local machine-agent skill directory. The command updates only shipped dgov skill names and leaves other skills alone.

dgov agents sync
dgov agents sync --skills-dir ~/.agents/skills

The canonical source is agent-guidance/skills/; packaged installs load the same bundle through dgov.agent_skill_data.

Plans

dgov init-plan

Create an empty plan tree at .dgov/plans/<name>/ with _root.toml and one section per name in --sections. Each section directory gets an _example.toml showing the unit shape. Underscore-prefixed files are ignored by compile.

dgov init-plan my-plan
dgov init-plan my-plan --sections tasks,docs

dgov plan create

Spawn the planner agent. The planner explores the codebase, asks clarifying questions unless --auto is set, drafts a plan tree, and writes it to disk.

dgov plan create "Add input validation to the signup form"
dgov plan create --auto "Refactor error handling in api.py"
dgov plan create --auto --run "Fix the off-by-one in pagination"

dgov compile

Walk the plan tree, merge units, resolve references, validate the DAG, bundle SOPs, and emit _compiled.toml. SOP bundling calls the LLM unless --dry-run is set.

dgov compile .dgov/plans/my-plan/
dgov compile .dgov/plans/my-plan/ --dry-run
dgov compile .dgov/plans/my-plan/ --graph

Compile fails closed on malformed SOPs, dangling dependencies, and file-claim conflicts between independent tasks.

dgov validate

Parse and validate a compiled plan without running it. Checks TOML syntax, dependency closure, file-claim conflicts, and agent resolvability.

dgov validate .dgov/plans/my-plan/_compiled.toml

dgov plan list

List plans under .dgov/plans/ with one-line deploy progress per plan. By default only active plans (the live .dgov/plans/<name>/ tree) are shown. Pass --archived to switch to plans under .dgov/plans/archive/, or --all to include both.

dgov plan list
dgov plan list --archived
dgov plan list --all
dgov --json plan list

Each entry reports the plan name, whether it has been compiled, deployed/total unit count, and one of these statuses: uncompiled, empty, compiled, in_progress, complete, stale, or degraded (human-readable output renders in_progress as in progress). stale means the compiled artifact is older than the source TOMLs; degraded means every unit deployed but a final-stage gate reported degradation. JSON mode emits the full per-plan payload, including run_status and remediation_needed.

dgov plan status

One-line deployment summary for a compiled plan: name, N/M deployed, and a staleness warning if the compile is older than the source TOMLs.

dgov plan status .dgov/plans/my-plan/
dgov plan status .dgov/plans/my-plan/ --verbose

dgov plan review

Post-hoc debrief of the last run for a plan. Scopes to the last run via the run-start marker. For each unit it shows: what landed, the number of self-corrected tool calls before done, the reject reason on failure, and diff stats.

dgov plan review .dgov/plans/my-plan/
dgov plan review my-plan/ --only tasks/main.add-feature
dgov plan review my-plan/ --diff tasks/main.add-feature
dgov plan review my-plan/ --events tasks/main.add-feature

If the live plan path does not exist but an archive copy is found, review resolves to the archive automatically and prints a note to stderr.

dgov plan remediate

Scaffold a follow-up plan for a fully deployed but degraded plan. Useful when every task merged but a final-stage gate reported degradation.

dgov plan remediate .dgov/plans/my-plan/
dgov plan remediate my-plan/ --name my-plan-cleanup

dgov archive-plan

Move a plan directory to .dgov/plans/archive/<name>.

dgov archive-plan my-plan

Successful runs auto-archive. Archives are local dgov bookkeeping and may live under ignored .dgov/ state in target repos. dgov does not require production repos to track .dgov/ solely for archive finalization. Use this command to archive manually.

Run

dgov run

Compile current source, then execute the plan. Each task runs in an isolated worktree with scoped settlement gates.

dgov run .dgov/plans/my-plan/
dgov run .dgov/plans/my-plan/ --restart
dgov run .dgov/plans/my-plan/ --continue
dgov run .dgov/plans/my-plan/ --only=tasks/main.add-feature

If the repo has no commits yet and only .dgov bootstrap files exist, dgov run creates the bootstrap snapshot automatically. With other uncommitted files present, it asks first.

dgov run requires sentrux to be installed. If .sentrux/baseline.json is missing, dgov run bootstraps it once before dispatch. A clean complete full-plan run refreshes accepted sentrux baseline metadata automatically after the post-run comparison passes. Refresh it explicitly with dgov sentrux gate-save when the baseline drift is intentional outside a full plan run. The baseline is governor-owned state; worker edits to .sentrux/baseline.json and .sentrux/dgov-baseline.json are rejected during review.

JSON output

In JSON mode (--json), dgov run emits structured results:

{
  "status": "complete",
  "succeeded": 3,
  "failed": 0,
  "sentrux": {
    "degradation": false,
    "quality_before": 85,
    "quality_after": 87
  },
  "duration_s": 45.23
}

If the post-run sentrux comparison detects degradation after all tasks merged, the status reports degraded, the exit code is zero, and the warning surfaces in the output. Task failures and abandoned tasks exit nonzero.

Recovery

There is no separate dgov recover command. Recovery flows through dgov run:

• bare dgov run <plan-dir> — surfaces abandoned work from a crashed prior run
• dgov run <plan-dir> --continue — retries failed or abandoned tasks
• dgov run <plan-dir> --restart — clears prior run state and starts fresh

dgov fix

Create and run a single-task plan. A thin wrapper around the standard pipeline.

dgov fix "Repair the off-by-one in pagination" -f src/pagination.py
dgov fix "Tighten error messages" -f src/api.py -f src/errors.py
dgov fix "Fix the auth bug" -f src/auth.py --commit-message "fix: auth race"

fix writes a transient plan under .dgov/runtime/fix-plans/fix-<slug>/, compiles it, runs it through the same gates as dgov run, and archives the plan under .dgov/runtime/fix-plans/archive/.

Observability

dgov status

Show the current governor state. By default, only live state from the latest run window for each plan. Pass --all for full event-derived history.

dgov status
dgov status --all
dgov --json status

Example output:

$ dgov status
status: active
tasks: 5 total
active: 2
tasks:
  active          add-feature
  pending         add-tests

--json is a global flag — place it before the subcommand.

dgov watch

Stream events in real time. Run this in a second terminal while a plan is executing. With no flags, watch follows the single current live plan. When that plan completes and a new single live plan starts, the watcher switches to the new plan and prints a divider.

dgov watch                    # follow the current live plan
dgov watch --all              # include events from all plans
dgov watch --plan my-plan     # pin one plan
dgov watch --root ../repo     # watch another checkout/root
dgov watch --ndjson           # emit line-delimited JSON

watch polls the SQLite event log in WAL mode, so it does not block the runner. Plan-scoped modes read from the latest run_start for that plan, so a rerun does not replay stale prior-run events. If watch starts while no single live plan exists, it tails from the current latest event id until a single live plan appears.

--ndjson is the app integration contract. It emits one JSON object per line:

{"type":"plan_selected","mode":"follow","from_plan":null,"to_plan":"my-plan","plan_name":"my-plan"}
{"type":"event","mode":"follow","id":42,"ts":"2026-06-23T16:00:00Z","event":"worker_log","pane":"pane-a","plan_name":"my-plan","task_slug":"tasks/main","payload":{"log_type":"thought","content":"reading files"}}

For a future Swift macOS app, prefer consuming dgov watch --ndjson as a subprocess first. Direct read-only SQLite WAL access is possible later, but it should not be the first implementation because it would duplicate the Python-owned plan-following, latest-run, and event-normalization semantics.

dgov tools audit

Summarize worker tool-call telemetry from the event log. Tells you which tools each worker used, how often, and at what cost in tool calls.

dgov tools audit
dgov tools audit --plan my-plan --role worker --limit 20

dgov diagnose

Report known governor failure shapes from the Failure-to-Task catalog in .dgov/governor.md. The command reads current repo state and recent settlement events, then prints typed next-action cards for matched failures.

dgov diagnose
dgov diagnose --root /path/to/project

dgov ledger

Operational ledger — record and query operational entries: bugs, fixes, rules, patterns, notes, debt, capabilities, and decisions. Backed by SQLite alongside the event log.

dgov ledger add <category> <content>
dgov ledger list [-c <category>] [-s <status>] [-q <keyword>]
dgov ledger resolve <id>

Categories: bug, fix, rule, pattern, note, debt, capability, decision.

Examples:

dgov ledger add bug "Race condition in task_runner.py on timeout"
dgov ledger add rule "Always use absolute imports; ruff-enforced"
dgov ledger add debt "Migrate persistence layer to async I/O"
 
dgov ledger list                            # open entries
dgov ledger list -c bug                     # open bugs only
dgov ledger list -q "race condition"        # keyword search
dgov ledger list -c rule -s resolved        # resolved rules
 
dgov ledger resolve 3                       # mark entry #3 resolved

dgov kb

Browse and validate the repo knowledge base under docs/knowledge/. Articles are Markdown files with strict frontmatter: stable ID, kind, status, canonical source paths, and related article IDs.

dgov kb list
dgov kb show sentrux
dgov kb validate
dgov --json kb list

dgov kb validate checks that article IDs are unique, sources exist and point outside the KB, related IDs resolve, and each article's first H1 matches its frontmatter title.

dgov kb graph

Dump the full knowledge graph: article nodes, source nodes, and edges.

dgov kb graph

In JSON mode, the payload contains articles, sources, and edges with relation values of source or related.

dgov kb related

Show article IDs reachable through related edges from a starting article, within a given depth.

dgov kb related sentrux
dgov kb related sentrux --depth 2

dgov kb path

Show the shortest related-edge path between two articles.

dgov kb path sentrux settlement-flow

dgov kb open

Open a knowledge base article in Obsidian. If the obsidian CLI is available, it calls obsidian open <path>; otherwise it prints an obsidian:// URI.

dgov kb open sentrux

Gates

dgov preflight

Run the settlement acceptance gates against the local working tree without spawning a worker. The result tells you whether the current checkout would pass the gates a dispatched task has to clear. It also checks dgov source policy drift: guidance mirrors, bootstrap policy packaging, and agent skill packaging must match the canonical repo files.

dgov preflight

dgov verify

Run named verification recipes from .dgov/project.toml.

dgov verify list
dgov verify run unit
dgov --json verify list

Recipe shape:

[verify.unit]
description = "Run unit tests"
command = "uv run pytest -q -m unit"

Both subcommands accept -r, --root TEXT.

dgov scope status

Preview the same file-claim scope status settlement uses for a task. With --plan, claims are loaded from a compiled plan or plan directory. Without --plan, use --claim and --read for ad hoc inspection.

dgov scope status --task tasks/main.a --plan .dgov/plans/my-plan/
dgov scope status --task my-task --claim src/a.py --read tests/test_a.py

dgov sentrux check

Run a sentrux architectural check against a directory.

dgov sentrux check
dgov sentrux check /path/to/project

dgov sentrux gate-save

Save or refresh .sentrux/baseline.json. In a git repo with no non-baseline working-tree changes, this also records .sentrux/dgov-baseline.json so stale-baseline checks know which commit was accepted. Commit both files when the refresh is intentional.

dgov sentrux gate-save

dgov sentrux gate

Compare the current sentrux state against the saved baseline. By default it prints degradation output without forcing a nonzero exit; pass --fail-on-degradation to make degradation fail the command.

dgov sentrux gate
dgov sentrux gate --fail-on-degradation

dgov sentrux offenders

List functions in the current snapshot that exceed length or complexity heuristics. The output ranks candidates for refactoring.

dgov sentrux offenders
dgov sentrux offenders /path/to/project

dgov sentrux status

Check whether sentrux is installed.

dgov sentrux status

Outputs sentrux: installed and available or sentrux: not found in PATH.

dgov coverage-baseline

Save or refresh the line-coverage baseline at .coverage-baseline/. This baseline is needed for settlement to compare coverage when coverage_cmd is set in project.toml.

dgov coverage-baseline

After a baseline exists, settlement rejects changed files whose measured line coverage drops by more than coverage_threshold percentage points.

Maintenance

dgov clean

Remove stale worktrees and output directories. Preserves anything tied to a live plan in the latest event window.

dgov clean
dgov clean --dry-run

What clean does:

1. Deletes everything under .dgov/out/.
2. Removes orphan worktrees and merged dgov/* branches git no longer tracks as live.
3. Removes transient fix plans from .dgov/runtime/fix-plans/ unless they belong to a currently live plan.
4. Preserves git-tracked inspection worktrees and fix plans for live plans.

dgov prune

Drop historical runtime artifact rows from the SQLite database. Lifecycle truth lives in the event log, so pruning artifact rows is safe; it only reduces operational bookkeeping.

dgov prune

Global options

--json is a global flag and must come before the subcommand:

dgov --json status
dgov --json run .dgov/plans/my-plan/
dgov --json ledger list

You can also enable JSON mode through the environment:

export DGOV_JSON=1
dgov status     # JSON output