CLI Reference

Complete reference for the dgov command-line interface.

Commands Overview

dgov fix

Create and run a single-task fix plan — a shortcut that generates a one-task plan and runs it through the normal compile/run pipeline.

dgov fix "Refactor error handling" --file src/utils.py --file src/main.py
dgov fix "Update docs" -f README.md -f docs/guide.md --name doc-update
dgov fix "Fix bug" -f src/core.py --commit-message "fix: resolve edge case"

Options

How It Works

The fix command is a thin wrapper around the standard plan pipeline:

1. Generates a transient plan directory under .dgov/runtime/fix-plans/fix-<slug>/
2. Creates a single task with the specified files
3. Compiles the plan to _compiled.toml
4. Runs the compiled plan through the normal executor

This uses the same compilation, settlement, and quality gates as dgov run. Transient fix plans are archived under .dgov/runtime/fix-plans/archive/.

dgov init-plan

Initialize a new plan directory under .dgov/plans/<name>/ with _root.toml and section stubs.

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

Options

dgov compile

Compile a plan tree into a dispatch-ready _compiled.toml. Walks the plan tree, merges units, resolves references, validates the DAG, and bundles SOPs.

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

Options

dgov validate

Parse and validate a plan file without running it. Checks dependencies, detects file-claim conflicts, and prints a summary of the DAG.

dgov validate <plan-dir>/_compiled.toml

dgov plan status

Show deployment status for a compiled plan — which units have been deployed via deployed.jsonl versus which are still pending. Warns if the compiled plan is stale relative to source TOML files.

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

dgov run

Execute a compiled plan directory or _compiled.toml file with isolated worktrees and Sentrux quality gates.

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

If the repo has no commits yet and only .dgov bootstrap files exist, dgov run creates the bootstrap snapshot automatically. If there are other uncommitted files, it asks before creating that bootstrap commit.

dgov run requires a saved Sentrux baseline at .sentrux/baseline.json. Create or refresh it explicitly with dgov sentrux gate-save. dgov run does not auto-save a new baseline.

Flags

Examples

dgov run .dgov/plans/feature-plan/ --restart

dgov run .dgov/plans/feature-plan/ --continue

dgov run .dgov/plans/feature-plan/ --only=tasks/main.add-tests

Output

The command outputs task progress to stderr and final results to stdout. In JSON mode (--json), it outputs structured data:

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

If the final post-run sentrux comparison detects degradation, the run exits nonzero even if all tasks merged.

dgov status

Show the current governor state. By default this surfaces only live task state; use --all to include persisted history.

dgov status
dgov status --all

Examples

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

$ dgov --json status
{
  "status": "active",
  "tasks": 5,
  "active": 2,
  "task_list": [
    {"slug": "add-feature", "state": "active"},
    {"slug": "add-tests", "state": "pending"}
  ]
}

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

dgov clean

Clean stale worktrees and output directories.

Use this when:

• Output directories accumulate and need periodic cleaning
• Inactive worktrees remain after task completion

dgov clean
dgov clean --dry-run

Options

Behavior

1. Deletes all directories from .dgov/out/
2. Removes worktrees from .dgov/worktrees/ that are not associated with active tasks
3. Removes transient fix plans from .dgov/runtime/fix-plans/ unless they belong to an ACTIVE task
4. Preserves worktrees and runtime fix plans for tasks in ACTIVE state

Examples

$ dgov clean
Deleted: .dgov/out/build-20240115
Deleted: .dgov/worktrees/fix-refactor-abc123
Preserved (active): .dgov/worktrees/feature-login-def456
Clean complete. Deleted 2 directories.

dgov recover

Recover from a crashed run — marks ACTIVE tasks as ABANDONED and removes orphaned worktrees and branches.

Use this when:

• A task crashed without proper cleaning
• You killed a run with Ctrl+C and need to recover
• Worktrees are left in a broken state

dgov recover

Behavior

1. Finds all tasks in ACTIVE, FAILED, or ABANDONED state
2. Removes their git worktrees
3. Marks ACTIVE tasks as ABANDONED in the persistence layer

Examples

$ dgov recover
Recovering 3 tasks...
  [removed worktree] add-feature
  [removed worktree] add-tests
  [skip worktree] fix-bug: worktree not found
Recovery complete: 2 tasks marked as ABANDONED.

dgov init

Bootstrap .dgov/project.toml and .dgov/governor.md for the current repository. Auto-detects language, source directory, and test directory.

dgov init
dgov init --force

Flags

Auto-Detection

The init command detects:

• Language: Python, JavaScript, Rust, or Go (by file prevalence)
• Source directory: src/, lib/, or current directory
• Test directory: tests/ or test/
• Tooling: Appropriate lint, format, and test commands

It also writes the repo-level OpenAI-compatible endpoint settings:

• default_agent
• llm_base_url
• llm_api_key_env

It also scaffolds .dgov/governor.md, the repo-local governor charter for:

• planning rules
• task authoring rules
• retry/failure rules
• done criteria

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

See LLM Providers for provider-specific examples.

Examples

$ dgov init
Created .dgov/project.toml
Created .dgov/governor.md
  language: python
  src_dir:  src/
  test_dir: tests/
Run `dgov sentrux gate-save` now to create the repo baseline? [Y/n]:
Next:
  1. Review .dgov/project.toml and .dgov/governor.md
  2. Refresh the architectural baseline with `dgov sentrux gate-save` when you intentionally reset it

$ dgov init --force
Created .dgov/project.toml
Created .dgov/governor.md
  language: python
  src_dir:  src/
  test_dir: tests/
Next:
  1. Review .dgov/project.toml and .dgov/governor.md
  2. Run `dgov sentrux gate-save` to create the repo baseline

dgov ledger

Operational ledger — record and list bugs, rules, and technical debt.

Subcommands

dgov ledger add

dgov ledger add <category> <content>

• bug — Known bugs or issues to address
• rule — Project conventions or rules
• debt — Technical debt to pay down

# Record a known bug
dgov ledger add bug "Race condition in task_runner.py when handling timeouts"
 
# Record a project rule
dgov ledger add rule "Always use absolute imports, ruff-enforced"
 
# Record technical debt
dgov ledger add debt "Refactor the persistence layer to use async I/O"

dgov ledger list

dgov ledger list [options]

# List all open entries
dgov ledger list
 
# List only bugs
dgov ledger list --category=bug
 
# Search for specific content
dgov ledger list --query="race condition"
 
# List resolved rules
dgov ledger list --category=rule --status=resolved

dgov ledger resolve

dgov ledger resolve <entry_id>

# Resolve entry #3
dgov ledger resolve 3
# Output: Resolved entry #3

Global Options

JSON Mode

Most commands support --json for machine-readable output:

dgov --json status
dgov --json run plan.toml
dgov --json ledger list

You can also enable JSON mode via environment variable:

export DGOV_JSON=1
dgov status  # Will output JSON