Getting Started

This guide walks you through installing govctl and creating your first governed artifact.

Requirements

Rust 1.88+ (uses edition 2024)

Installation

# From crates.io
cargo install govctl

# With TUI dashboard feature
cargo install govctl --features tui

# Or build from source
git clone https://github.com/govctl-org/govctl
cd govctl
cargo build --release
# Binary at ./target/release/govctl

# Build with TUI
cargo build --release --features tui

Optional Features

Feature	Description	Dependencies
`tui`	Interactive terminal dashboard (`govctl tui`)	ratatui, crossterm

Shell Completion

Generate completion scripts for your shell:

# Bash
govctl completions bash > ~/.local/share/bash-completion/completions/govctl

# Zsh (add to your .zshrc or install to completion directory)
govctl completions zsh > ~/.zsh/completions/_govctl
# Then add to fpath: fpath=(~/.zsh/completions $fpath)

# Fish
govctl completions fish > ~/.config/fish/completions/govctl.fish

# PowerShell (add to your profile)
govctl completions powershell >> $PROFILE

Restart your shell or source the configuration to enable tab completion.

Initialize a Project

govctl init

This creates the governance directory structure:

gov/
├── config.toml       # Configuration
├── rfc/              # RFC sources
├── adr/              # ADR sources
├── work/             # Work item sources
├── schema/           # JSON schemas
└── templates/        # New artifact templates

Create Your First RFC

govctl rfc new "Feature Title"

This creates gov/rfc/RFC-0000/rfc.json with the RFC metadata.

Add a Clause

RFCs are composed of clauses — atomic units of specification:

govctl clause new RFC-0000:C-SCOPE "Scope" -s "Specification" -k normative

Edit Clause Content

govctl clause edit RFC-0000:C-SCOPE --stdin <<'EOF'
The feature MUST do X.
The feature SHOULD do Y.
EOF

Validate Everything

govctl check

This validates all governance artifacts against the schema and phase rules.

Render to Markdown

govctl render

Generates human-readable markdown in docs/rfc/RFC-0000.md.

Adopting govctl in an Existing Project

govctl init is safe to run in existing repositories — it only creates the gov/ directory structure alongside existing files.

For AI-assisted migration, use the /migrate skill to systematically discover undocumented decisions, backfill ADRs, and annotate source code with [[...]] references.

Next Steps

Working with RFCs — Full RFC lifecycle
Working with ADRs — Decision records
Working with Work Items — Task tracking
Validation & Rendering — Quality gates

Keyboard shortcuts

govctl