Skip to content

CLI Quickstart

The aegis CLI is included with the Python package and provides command-line access to the AEGIS governance engine.

Prerequisites

pip install aegis-governance

Check Version

aegis version

Output:

{
  "aegis_governance": "1.0.0",
  "python": "3.11.9"
}

Evaluate a Proposal

Pipe JSON from stdin

echo '{
  "proposal_summary": "Add Redis caching layer",
  "estimated_impact": "medium",
  "risk_proposed": 0.3,
  "complexity_score": 0.6,
  "quality_score": 0.8,
  "novelty_score": 0.4
}' | aegis evaluate

Read from a file

aegis evaluate --input proposal.json

With a custom configuration

aegis evaluate --input proposal.json --config config.yaml

Shadow mode (observe without enforcing)

aegis evaluate --input proposal.json --shadow

With drift detection

Provide a JSON file containing a baseline array of historical values:

aegis evaluate --input proposal.json --drift-baseline baseline.json

Validate a Configuration File

Check that a YAML config file parses correctly and all parameters are within valid ranges:

aegis validate-config schema/interface-contract.yaml

Output on success:

{
  "valid": true,
  "parameters": {
    "epsilon_R": 0.01,
    "epsilon_P": 0.01,
    "risk_trigger_factor": 2.0,
    ...
  }
}

Health Check

Verify that the AEGIS engine, gate evaluator, and optional subsystems are operational:

aegis health

Prometheus Metrics

Dump current Prometheus metrics in text exposition format (requires the telemetry optional dependency):

aegis metrics

Exit Codes

Code Meaning
0 PROCEED — proposal passed all gates
1 HALT — proposal failed one or more gates
2 PAUSE / ESCALATE — human review required

Using in CI/CD Pipelines

The exit code maps directly to governance outcomes, making aegis evaluate a natural fit for pipeline gates.

GitHub Actions

- name: AEGIS Governance Gate
  run: |
    echo '${{ toJSON(github.event) }}' | jq '{
      proposal_summary: .head_commit.message,
      estimated_impact: "medium",
      risk_proposed: 0.3,
      complexity_score: 0.5,
      quality_score: 0.8
    }' | aegis evaluate
    EXIT_CODE=$?
    if [ $EXIT_CODE -eq 1 ]; then
      echo "::error::AEGIS governance gate HALTED this change"
      exit 1
    elif [ $EXIT_CODE -eq 2 ]; then
      echo "::warning::AEGIS governance gate requires human review"
      # Optionally create a review request here
    fi

Shell Script

#!/usr/bin/env bash
set -euo pipefail

aegis evaluate --input proposal.json --config config.yaml
exit_code=$?

case $exit_code in
  0) echo "PROCEED: all gates passed" ;;
  1) echo "HALT: governance gate failed"; exit 1 ;;
  2) echo "PAUSE: escalation required"; exit 1 ;;
  *) echo "UNEXPECTED: exit code $exit_code"; exit 1 ;;
esac

Proposal JSON Schema

The evaluate command accepts the following fields. Only proposal_summary and estimated_impact are required; all numeric fields default to safe values.

Field Type Default Description
proposal_summary string "CLI evaluation" Description of the proposed change
estimated_impact string "medium" Impact level: low, medium, high, critical
phase string "plan" PCW phase: plan, commit, work
risk_proposed float 0.0 Proposed risk score (0-1)
risk_baseline float 0.0 Baseline risk score (0-1)
profit_proposed float 0.0 Proposed profit metric
profit_baseline float 0.0 Baseline profit metric
complexity_score float 0.5 Complexity score (0-1)
quality_score float 0.7 Quality score (0-1)
novelty_score float 0.5 Novelty score (0-1)
quality_subscores list [0.7, 0.7, 0.7] Per-dimension quality scores
requires_human_approval bool false Force human review
time_sensitive bool false Time-sensitive proposal
reversible bool true Whether the change is reversible
metadata object {} Arbitrary key-value metadata

Simplified aliases are also accepted: risk for risk_proposed, profit for profit_proposed, complexity for complexity_score, quality for quality_score, novelty for novelty_score.

Next Steps