Skip to main content

CLI Commands

Complete reference for all Rigour CLI commands.

rigour check​

Validate staged changes against safety rules.

rigour check [options]

Options​

FlagDescription
--ciCI mode with strict exit codes
--jsonOutput results as JSON. Note: In v2.1+, all debug/info logs are silenced from stdout when this flag is active, ensuring stdout contains valid, parsable JSON.
--config <path>Path to a custom rigour.yml or rigour_config.yaml. Useful for ephemeral benchmarking or CI overrides.

Examples​

# Basic check
npx rigour check

# CI pipeline
npx rigour check --ci --json

# Custom config
npx rigour check --config ./custom-rigour.yaml

rigour init​

Initialize Rigour in your project. This command creates a rigour.yml file and can automatically detect your project's role and coding paradigm.

npx rigour init [options]

Options​

FlagDescription
--preset <name>Explicitly set a Project Role (api, ui, infra, data)
--paradigm <name>Explicitly set a Coding Paradigm (oop, functional)
--forceOverwrite existing rigour.yml config

Project Roles (--preset)​

Roles define the high-level engineering standards and gate thresholds.

RoleTargetKey Differentiators
apiBackend Services400 line limit, strict SOLID enforcement
uiWeb/Frontends300 line limit, JSX-aware complexity
infraIaC (Terraform)Protected .github/ and CI configs
dataData/ML Pipelines500 line limit, reproducibility gates

Coding Paradigms (--paradigm)​

Paradigms layer specific AST (Abstract Syntax Tree) rules on top of your role.

ParadigmKey Gates
oopMax inheritance depth (3), Method counts (10/class)
functionalMax nesting (3), Function length (40 lines)

Examples​

# Default initialization (Auto-discovery)
npx rigour init

# Explicitly use API role with OOP paradigm
npx rigour init --preset api --paradigm oop

Framework Compatibility (Safe Scaffolding)​

Many framework CLI tools (like create-next-app or npm init vite) require the target directory to be completely empty. If you run rigour init first, these tools will fail.

Best Practice:

  1. Run your framework initializer first.
  2. Run rigour init second to layer your engineering standards on top.

If you already initialized Rigour: Simply move rigour.yml and the docs/ folder aside temporarily, run your framework command, and move them back. AI Agents using Rigour have a built-in workflow to handle this automatically.

rigour explain​

Get detailed explanation of validation results.

npx rigour explain [options]

Options​

FlagDescription
--fix-packet <path>Analyze a specific fix packet
--verboseInclude AST details

Examples​

# Explain last check
npx rigour explain

# Analyze fix packet
npx rigour explain --fix-packet ./fix.json

rigour run​

The Supervisor Loop. Executes an AI agent and automatically iterates until quality gates pass.

npx rigour run [options] -- <agent-command>

The Iterative Refinement Cycle​

When you use rigour run, Rigour manages a stateful refinement loop:

  1. Deploy: Your agent (e.g., Claude Code) is executed with your prompt.
  2. Snapshot: Rigour monitors file changes in real-time.
  3. Audit: Quality gates are checked against the resulting state.
  4. Refine: If gates fail, Rigour generates a rigour-fix-packet.json (Diagnostic) and automatically re-invokes the agent to fix the violations.
  5. Finish: The loop exits when all gates PASS or the maximum iterations are reached.

🌗 Rigour Modes​

ModeControlUse CaseLoop
AdvisorSuggestiveCode reviews & IDE suggestionsSingle pass
SupervisorEnforcementCI/CD gates & Autonomous agentsIterative (Auto-fix)

[!TIP] Rigour CI/CD workflows primarily use Supervisor mode to ensure code quality through iterative refinement.

Options​

FlagDefaultDescription
--iterations <n>3Maximum number of refinement cycles
--fail-fastfalseTerminate instantly on the first violation

Safety Rails​

rigour run prevents "agent explosions" by monitoring the cycle delta. If an agent changes more than max_files_changed_per_cycle (set in rigour.yml), the loop is instantly aborted.

rigour studio​

The Governance Control Room. A premium, local-first dashboard for real-time AI shadowing, pattern discovery, and HITL (Human-in-the-Loop) arbitration.

rigour studio [options]

The Shadowing Experience​

Rigour Studio provides a high-fidelity interface for monitoring AI agents as they work on your local machine:

  1. Live Shadowing: See tool calls and filesystem changes as they happen.
  2. Pattern Index: Visually search and explore project patterns (supports AI-powered Semantic Search).
  3. Governance Audit: Deep-dive into proposed changes before they are committed.
  4. HITL Arbitration: Manually Approve (Override) or Reject AI actions directly from the UI.

Options​

FlagDefaultDescription
--port <n>3000Port to run the Studio dashboard on
--devtrueRun in development mode (recommended for v2)

Key Features​

  • Memory Bank: Visualize the agent's persistent memory and contextual state.
  • Quality Gates: Real-time visualization of gate violations and compliant code.
  • Diff Viewer: High-fidelity Monaco-based diffing for every AI interaction.

Technical Reference: The Quality Score​

Rigour calculates a Total Quality Score (0-100) for every audit run. This score is included in the JSON report and displayed in human-readable summaries.

How it's calculated:​

  • Base Score: 100
  • Structural Violations: -5 points per failure (e.g., SME_COGNITIVE_LOAD).
  • Security Violations: -10 points per failure (e.g., SME_SECURITY_SINK).
  • Dynamic Violations: -15 points per blind spot (e.g., DYNAMIC_COVERAGE_LOW).
CodeMeaningContext
0PASSAll quality gates were satisfied (Score > Threshold).
1FAILOne or more engineering violations were found.
2CONFIG_ERRORrigour.yml is missing or invalid.
3INTERNAL_ERRORUnexpected diagnostic or filesystem failure.

See the Exit Codes Guide for advanced usage.