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 -e ".[dev]"

Source access requires a BSL-1.1 license.

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

Utility auto-synthesis: If utility_result is not provided (the common case), the CLI auto-synthesizes it from profit_baseline/profit_proposed using symmetric PERT three-point estimation (±20% spread) with a profit delta epsilon clamp of 0.001. This matches MCP server and REST API behaviour.

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.1.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.

aegis admin create-customer

Create a new customer record in DynamoDB.

aegis admin create-customer --name NAME --email EMAIL [--company COMPANY] [--tier TIER] [--api-key-id ID] [--table TABLE] [--region REGION]

Options:

Option	Description
`--name NAME`	Customer name (required)
`--email EMAIL`	Customer email (required)
`--company COMPANY`	Company name
`--tier TIER`	Pricing tier: `community`, `professional`, `enterprise`, `financial_services` (default: `community`). Aliases `free` and `pro` are also accepted.
`--api-key-id ID`	AWS API Gateway API key ID to associate with this customer
`--table TABLE`	DynamoDB table name (default: `AEGIS_TABLE_NAME` env var)
`--region REGION`	AWS region (default: `us-west-2`)

Examples:

# Minimal
aegis admin create-customer --name "Acme Corp" --email "admin@acme.example.com"

# Full options
aegis admin create-customer \
  --name "Acme Corp" \
  --email "admin@acme.example.com" \
  --company "Acme Inc." \
  --tier professional \
  --api-key-id abc123xyz

Example output:

{
  "customer_id": "cust_a1b2c3d4e5f6",
  "name": "Acme Corp",
  "email": "admin@acme.example.com",
  "company": "Acme Inc.",
  "tier": "pro",
  "status": "active",
  "api_key_id": "abc123xyz",
  "created_at": "2026-03-05T12:00:00+00:00",
  "updated_at": "2026-03-05T12:00:00+00:00",
  "metadata": {}
}

aegis admin list-customers

List all customer records.

aegis admin list-customers [--table TABLE] [--region REGION]

Options:

Option	Description
`--table TABLE`	DynamoDB table name (default: `AEGIS_TABLE_NAME` env var)
`--region REGION`	AWS region (default: `us-west-2`)

Example:

aegis admin list-customers

Example output:

{
  "count": 2,
  "customers": [
    {
      "customer_id": "cust_a1b2c3d4e5f6",
      "name": "Acme Corp",
      "email": "admin@acme.example.com",
      "company": "Acme Inc.",
      "tier": "pro",
      "status": "active",
      "api_key_id": "abc123xyz",
      "created_at": "2026-03-05T12:00:00+00:00",
      "updated_at": "2026-03-05T12:00:00+00:00",
      "metadata": {}
    }
  ]
}

aegis admin get-customer

Get a single customer by ID.

aegis admin get-customer CUSTOMER_ID [--table TABLE] [--region REGION]

Arguments:

Argument	Description
`CUSTOMER_ID`	Customer ID (e.g., `cust_a1b2c3d4e5f6`)

Options:

Option	Description
`--table TABLE`	DynamoDB table name (default: `AEGIS_TABLE_NAME` env var)
`--region REGION`	AWS region (default: `us-west-2`)

Example:

aegis admin get-customer cust_a1b2c3d4e5f6

Example output:

{
  "customer_id": "cust_a1b2c3d4e5f6",
  "name": "Acme Corp",
  "email": "admin@acme.example.com",
  "company": "Acme Inc.",
  "tier": "pro",
  "status": "active",
  "api_key_id": "abc123xyz",
  "created_at": "2026-03-05T12:00:00+00:00",
  "updated_at": "2026-03-05T12:00:00+00:00",
  "metadata": {}
}

aegis admin usage

Get usage summary for a customer for a given month.

aegis admin usage CUSTOMER_ID [--month YYYY-MM] [--table TABLE] [--region REGION]

Arguments:

Argument	Description
`CUSTOMER_ID`	Customer ID (e.g., `cust_a1b2c3d4e5f6`)

Options:

Option	Description
`--month YYYY-MM`	Month to query (default: current month)
`--table TABLE`	DynamoDB table name (default: `AEGIS_TABLE_NAME` env var)
`--region REGION`	AWS region (default: `us-west-2`)

Examples:

# Current month
aegis admin usage cust_a1b2c3d4e5f6

# Specific month
aegis admin usage cust_a1b2c3d4e5f6 --month 2026-03

Example output:

{
  "customer_id": "cust_a1b2c3d4e5f6",
  "month": "2026-03",
  "total_evaluations": 142,
  "total_risk_checks": 28,
  "total_calls": 170,
  "channels": {},
  "daily_breakdown": [
    {
      "day": "01",
      "evaluate_count": 12,
      "risk_check_count": 3,
      "total_calls": 15
    }
  ]
}

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.
`AEGIS_TABLE_NAME`	DynamoDB table name for customer management. Used by `aegis admin` commands. Defaults to `aegis-governance-state-dev`.
`AWS_DEFAULT_REGION`	AWS region for DynamoDB operations. Used by `aegis admin` commands. Defaults to `us-west-2`.

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.6
  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

On this page