Hosted CLI Tutorial (Axis + Aegis)

This tutorial is a hosted-cloud path for operators using axis.velikey.com with the aegis CLI.

What this run validates

Axis connectivity from CLI.
API-token auth for machine workflows.
Session-token auth for hosted policy-read routes.
Core command coverage without local control-plane deployment.

1) Customer onboarding prerequisites

Create an account on https://axis.velikey.com/auth/signup.
Verify email through the verification link sent by Axis.
Sign in.
Open Dashboard -> Settings -> API Keys and create an API key.

Warning

Email verification is required before credential sign-in can complete.

2) Install CLI

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

3) Configure hosted Axis connection

export AEGIS_CONTROL_PLANE_URL="https://axis.velikey.com"
export AEGIS_API_TOKEN="<your_api_key>"

4) Run API-token command set

# Health check
aegis status

# Agent inventory
aegis agent list

# Derived metrics from hosted inventory
aegis metrics

# Cipher suite catalog (includes PQ-focused view)
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

# OHTTP configuration helper
aegis ohttp config

5) Policy-read commands (session token)

Hosted policy list/show currently use session-auth routes.

export AEGIS_SESSION_TOKEN="<nextauth_session_token>"
aegis policy list
aegis policy show <policy_id>

Current hosted limitation

aegis policy create and aegis policy template are not yet available on hosted policy-write APIs. Use Axis dashboard policy management for create/apply operations.

6) Quick CI smoke (hosted)

# .github/workflows/axis-cli-smoke.yml
- name: Aegis CLI Hosted Smoke
  run: |
    aegis status
    aegis agent list
    aegis suites list --pq-only

7) Troubleshooting

404 /healthz or 404 /ui/api/*: use latest CLI binary.
401 on agent list: missing/invalid AEGIS_API_TOKEN.
401 on policy list: missing/invalid AEGIS_SESSION_TOKEN.
No agents found: token is valid but tenant has no enrolled agents yet.