User Guide

Comprehensive guide to using Governix CLI and MCP Server.

CLI Reference

governix init

Initialize a governance framework in a target directory.

bashUsage: governix init [flags]

Flags:
  -i, --interactive    Interactive mode with prompts
  -d, --dir string     Target directory path (default: current dir)
  -f, --force          Overwrite existing .governance directory

Tip: Use --interactive on first run to see the full setup flow. Use --dir to initialize in a specific project.

governix status

Check the health of your governance framework.

bashUsage: governix status [flags]

Flags:
  -d, --dir string     Target directory path (default: current dir)
  -v, --verbose        Show detailed role and rule info

governix dashboard

Start the web-based governance dashboard.

bashUsage: governix dashboard [flags]

Flags:
  -p, --port int       HTTP server port (default: 8080)
  -d, --dir string     Governance directory path (default: current dir)

governix version

Display the installed version and build information.

bashUsage: governix version

MCP Server Integration

The MCP Server (governix-mcp) operates in two modes:

Mode 1: JSON-RPC 2.0 (stdio)

Default mode. Used by AI IDEs to communicate via standard input/output.

bash# Start as MCP stdio server
governix-mcp

# With custom governance path
GOVERNANCE_PATH=/path/to/project governix-mcp

Mode 2: HTTP Server

Start as an HTTP server with governance API endpoints.

bash# Start on port 8080
governix-mcp -http :8080

The HTTP server provides three REST API endpoints:

Endpoint	Description
`GET /api/governance/status`	Governance health check
`GET /api/governance/roles`	List all governance roles
`GET /api/governance/heartbeat`	Heartbeat status

Governance Directory Structure

Running governix init creates the following structure:

text.governance/
  charter.md          # Governance charter
  HEARTBEAT.md        # Heartbeat tracking
  VERSION             # Version file
  rules/              # Governance rules
  prompts/            # Role-specific prompts
  attention/          # Attention management
  discussions/        # Consensus records
  registry/           # Input/Output registry
  status/             # Status tracking

Best Practices

Version Control: Always commit your .governance/ directory to git
Regular Status Checks: Run governix status daily to ensure governance health
Dashboard Monitoring: Keep the dashboard running for real-time visibility
Update Prompts: Customize role prompts to match your team's domain
Heartbeat Tracking: Heartbeats are automatically tracked — review them weekly