Skip to content

Aegis CLI Reference (Hosted Axis)

This reference reflects the current aegis CLI command surface and hosted Axis API behavior.

Installation

curl -L https://github.com/velikey/aegis/releases/latest/download/aegis-cli-linux-amd64.tar.gz | tar xz
sudo mv aegis /usr/local/bin/
aegis --version

Authentication

The CLI supports two auth modes:

  • AEGIS_API_TOKEN for machine/API-key routes.
  • AEGIS_SESSION_TOKEN for hosted session routes.

Set control plane URL in all cases:

export AEGIS_CONTROL_PLANE_URL="https://axis.velikey.com"

Create an API key in Axis (Dashboard -> Settings -> API Keys), then:

export AEGIS_API_TOKEN="<your_api_key>"

Session Token (required for some policy-read routes)

If you need policy read operations against hosted routes that currently require session auth:

export AEGIS_SESSION_TOKEN="<nextauth_session_token>"

Command Matrix (Hosted Axis)

Verified working now

# Health + connectivity
aegis status

# Agent inventory (API key auth)
aegis agent list

# Summary metrics derived from hosted agent inventory
aegis metrics

# Cipher suites (local catalog)
aegis suites list
aegis suites list --pq-only
aegis suites show VELI-DEFAULT-2025

# Local key operations
aegis keys generate kem --suite VELI-DEFAULT-2025 --format json
aegis keys list

# OHTTP utility commands
aegis ohttp config

Works with session token

aegis policy list
aegis policy show <policy_id>

Not yet supported on hosted Axis API

These commands currently return an explicit "not available via hosted Axis API yet" error:

aegis policy create <id> "<name>" @policy.json
aegis policy template soc2 --id <id>

Use the Axis dashboard policy management UI for create/apply until hosted policy-write routes are available.

Troubleshooting

  • 404 /healthz or 404 /ui/api/*: upgrade to the latest CLI build (hosted endpoints are /api/*).
  • 401 on aegis agent list: verify AEGIS_API_TOKEN.
  • 401 on aegis policy list: add AEGIS_SESSION_TOKEN or use the dashboard.