CLI Reference¶

aegis -- Command-line interface for the AEGIS Governance Decision SDK.

Installation¶

The aegis command is installed as a console entry point when you install the package:

pip install aegis-governance[dev]

Commands¶

aegis evaluate¶

Evaluate a proposal through all six AEGIS governance gates (Risk, Profit, Novelty, Complexity, Quality, Utility). Outputs a JSON decision to stdout.

aegis evaluate [--input FILE] [--config FILE] [--shadow] [--telemetry-url URL] [--drift-baseline FILE]

Options:

Option	Short	Description
`--input FILE`	`-i`	Path to proposal JSON file. If omitted, reads from stdin.
`--config FILE`	`-c`	Path to AEGIS YAML config file. Defaults to built-in frozen parameters.
`--shadow`		Run in shadow mode (evaluate without enforcing decisions). Gates still evaluate normally but results are advisory only. Use for 30+ days of calibration before enforcing drift thresholds.
`--telemetry-url URL`		HTTPS URL to POST structured telemetry events to. Subject to SSRF validation.
`--drift-baseline FILE`		Path to JSON file containing a baseline data array (30+ numbers) for KL divergence drift detection.

Input JSON format:

The input JSON can use either full PCWContext field names or simplified aliases:

Field	Alias	Type	Default	Description
`proposal_summary`		`string`	`"CLI evaluation"`	Brief description
`estimated_impact`		`string`	`"medium"`	`low`, `medium`, `high`, `critical`
`risk_proposed`	`risk`	`number`	`0.0`	Predicted risk after change (0.0-1.0)
`risk_baseline`	`risk_base`	`number`	`0.0`	Current risk level (0.0-1.0)
`profit_proposed`	`profit`	`number`	`0.0`	Expected profit after change
`profit_baseline`	`profit_base`	`number`	`0.0`	Current profit metric
`novelty_score`	`novelty`	`number`	`0.5`	How novel the proposal is (0.0-1.0)
`complexity_score`	`complexity`	`number`	`0.5`	Normalized complexity, higher = simpler (0.0-1.0)
`quality_score`	`quality`	`number`	`0.7`	Overall quality (0.0-1.0)
`risk_score`		`number`		Alias for `risk_proposed` (used only if `risk_proposed` and `risk` are absent)
`quality_subscores`		`array[number]`	`[0.7, 0.7, 0.7]`	Detailed quality subscores
`phase`		`string`	`"plan"`	Lifecycle phase: `plan`, `commit`, `work`
`agent_id`		`string`	`"aegis-cli"`	Agent identifier
`session_id`		`string`	(auto UUID)	Session identifier
`requires_human_approval`		`boolean`	`false`	Force human approval
`time_sensitive`		`boolean`	`false`	Mark as time-sensitive
`reversible`		`boolean`	`true`	Whether action is reversible
`metadata`		`object`	`{}`	Additional key-value metadata

Examples:

# From file
aegis evaluate --input proposal.json

# From stdin (pipe)
echo '{"proposal_summary":"Add cache","estimated_impact":"low","risk":0.1}' | aegis evaluate

# With custom config
aegis evaluate --input proposal.json --config my-config.yaml

# Shadow mode with drift baseline
aegis evaluate --input proposal.json --shadow --drift-baseline baseline.json

# With telemetry
aegis evaluate --input proposal.json --telemetry-url https://telemetry.example.com/events

Example proposal.json:

{
  "proposal_summary": "Deploy authentication service v2",
  "estimated_impact": "high",
  "risk_proposed": 0.3,
  "risk_baseline": 0.1,
  "profit_proposed": 1500,
  "profit_baseline": 1000,
  "novelty_score": 0.6,
  "complexity_score": 0.7,
  "quality_score": 0.85,
  "requires_human_approval": true
}

Example output:

{
  "status": "escalate",
  "confidence": 0.876543,
  "gates_passed": 5,
  "gates_failed": 1,
  "failing_gates": ["utility"],
  "rationale": "High impact proposal with failing gates: utility",
  "next_steps": [
    "Escalate to Risk Lead for review",
    "Prepare justification document"
  ],
  "constraints": [],
  "decision_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-02-24T12:00:00+00:00",
  "override_eligible": true,
  "override_requires": ["risk_lead", "security_lead"],
  "gates": {
    "risk": {
      "passed": true,
      "value": 0.15,
      "threshold": 2.0,
      "confidence": 0.95,
      "message": "Risk gate passed"
    }
  }
}

aegis validate-config¶

Validate an AEGIS YAML configuration file. Outputs the parsed parameters as JSON on success.

aegis validate-config CONFIG_FILE

Arguments:

Argument	Description
`CONFIG_FILE`	Path to YAML config file to validate

Examples:

# Validate the frozen parameter schema
aegis validate-config schema/interface-contract.yaml

# Validate a custom config
aegis validate-config my-config.yaml

Example output (valid):

{
  "valid": true,
  "parameters": {
    "epsilon_R": 0.01,
    "epsilon_P": 0.01,
    "risk_trigger_factor": 2.0,
    "profit_trigger_factor": 2.0,
    "trigger_confidence_prob": 0.95
  }
}

Example output (invalid):

{
  "valid": false,
  "error": "tau_warning (0.6) must be less than tau_critical (0.5)"
}

aegis version¶

Show AEGIS version and Python version information.

aegis version

Example output:

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

aegis health¶

Run a system health check. Verifies that core components (configuration, gate evaluator, persistence, Prometheus) can be initialized correctly.

aegis health

Example output (healthy):

{
  "healthy": true,
  "checks": {
    "config": {
      "ok": true,
      "epsilon_R": 0.01
    },
    "gates": {
      "ok": true,
      "risk_gate_functional": true
    },
    "persistence": {
      "ok": true,
      "available": false
    },
    "prometheus": {
      "ok": true,
      "available": false
    }
  }
}

The available field indicates whether optional dependencies (SQLAlchemy, prometheus_client) are installed. The health check passes even when optional dependencies are absent.

aegis metrics¶

Dump current Prometheus metrics in text exposition format. Requires the prometheus_client package.

aegis metrics

Example output:

# HELP aegis_decisions_total Total governance decisions
# TYPE aegis_decisions_total counter
aegis_decisions_total{status="proceed"} 42.0
aegis_decisions_total{status="halt"} 3.0

If prometheus_client is not installed, this command exits with code 1 and prints an error message.

Exit Codes¶

Code	Meaning	Description
`0`	PROCEED	All gates passed, safe to continue
`1`	HALT	Decision halted (or command error)
`2`	PAUSE / ESCALATE	Requires human review or escalation

These exit codes enable shell scripting integration:

aegis evaluate --input proposal.json
case $? in
  0) echo "Proceeding with deployment" ;;
  1) echo "HALTED -- cannot proceed" ; exit 1 ;;
  2) echo "Waiting for human approval" ;;
esac

Environment Variables¶

Variable	Description
`AEGIS_CONFIG_PATH`	Default path to AEGIS YAML config file (used when `--config` is not specified). Falls back to built-in defaults if not set.

Configuration File¶

The CLI accepts YAML configuration files that follow the schema/interface-contract.yaml format. Use --config with the evaluate command or validate-config to check a file before use.

Example config excerpt:

parameters:
  epsilon_R: 0.01
  epsilon_P: 0.01
  risk_trigger_factor: 2.0
  profit_trigger_factor: 2.0
  trigger_confidence_prob: 0.95
  novelty_gate:
    N0: 0.7
    k: 10.0
    output_threshold: 0.8
  complexity_floor: 0.5
  quality_min_score: 0.7
  quality_no_zero_subscore: true
  kl_drift:
    tau_warning: 0.3
    tau_critical: 0.5
    window_days: 30

Piping and Scripting¶

The CLI is designed for integration into CI/CD pipelines and shell scripts. All output is JSON, all errors go to stderr, and exit codes map directly to decision outcomes.

# Generate proposal JSON dynamically and pipe to aegis
python generate_proposal.py | aegis evaluate --config prod-config.yaml

# Use jq to extract specific fields
aegis evaluate --input proposal.json | jq '.status'

# Combine with drift baseline for production
aegis evaluate \
  --input proposal.json \
  --config schema/interface-contract.yaml \
  --drift-baseline baselines/current.json \
  --telemetry-url https://telemetry.internal/events