hoziron-cli auth

Authentication and API key management.

Synopsis

hoziron-cli auth <subcommand> [options]

Subcommands

Subcommand	Description
`create-key`	Create a new API key
`list-keys`	List all active API keys
`revoke-key <id>`	Revoke an API key
`rotate-key <id>`	Rotate a key (revoke + recreate)
`whoami`	Show current caller identity

There is no hash-password subcommand — AuthCommands has no such variant, and dashboard/console auth is handled via the local/oidc auth modes described in authentication.md, not a standalone password-hashing utility.

hoziron-cli auth create-key

Create a new API key for programmatic access.

hoziron-cli auth create-key --role <role> --name <name> [--expires-in <duration>] [--json]

Flags

Flag	Description
`--role <role>`	Key role (admin, operator, developer, viewer, service)
`--name <name>`	Human-readable name
`--expires-in <duration>`	Expiration (e.g., "90d", "24h", "365d"). Omit for no expiration
`--json`	JSON output

Roles

Role	Access Level
`admin`	Full access — all operations including key management
`operator`	Manage agents, competencies, workflows; no key/auth management
`developer`	Send messages, view status; no lifecycle management
`viewer`	Read-only access to status, health, metrics
`service`	Machine-to-machine — scoped to specific operations

Examples

# Create an operator key for CI
$ hoziron-cli auth create-key --role operator --name "ci-deploy-bot" --expires-in 90d
✓ API key created

  Key ID:   key-a1b2c3d4
  Name:     ci-deploy-bot
  Role:     operator
  Expires:  2026-09-02

  API Key:  hzn_sk_a1b2c3d4e5f6...

  ⚠ Save this key now — it won't be shown again.

# Create a viewer key for monitoring
$ hoziron-cli auth create-key --role viewer --name "grafana-scraper"
✓ API key created (no expiration)

  Key ID:   key-e5f6a7b8
  API Key:  hzn_sk_e5f6a7b8c9d0...

# Create a service key
$ hoziron-cli auth create-key --role service --name "claims-webhook-handler" --expires-in 365d
✓ API key created

hoziron-cli auth list-keys

$ hoziron-cli auth list-keys
ID            NAME                  ROLE      EXPIRES      CREATED
key-a1b2c3d4  ci-deploy-bot         operator  2026-09-02   2026-06-04
key-e5f6a7b8  grafana-scraper       viewer    never        2026-06-04
key-f6a7b8c9  claims-webhook        service   2027-06-04   2026-06-04

$ hoziron-cli auth list-keys --json
[
  {
    "id": "key-a1b2c3d4",
    "name": "ci-deploy-bot",
    "role": "operator",
    "expires_at": "2026-09-02T00:00:00Z",
    "created_at": "2026-06-04T10:00:00Z"
  }
]

hoziron-cli auth revoke-key

Immediately invalidate an API key.

$ hoziron-cli auth revoke-key key-a1b2c3d4
✓ Key 'ci-deploy-bot' (key-a1b2c3d4) revoked

# Revoked keys are removed from list
$ hoziron-cli auth list-keys
ID            NAME                  ROLE      EXPIRES      CREATED
key-e5f6a7b8  grafana-scraper       viewer    never        2026-06-04

hoziron-cli auth rotate-key

Revoke the old key and create a new one with the same name and role.

$ hoziron-cli auth rotate-key key-e5f6a7b8
✓ Key rotated

  Old key revoked: key-e5f6a7b8
  New key created: key-c9d0e1f2

  API Key: hzn_sk_c9d0e1f2a3b4...

  ⚠ Update all systems using the old key.

hoziron-cli auth whoami

Show the current caller's identity and role. Backed by GET /auth/whoami, which resolves whichever credential the request actually presented (API key, static token, or OIDC token).

$ hoziron-cli auth whoami
Identity: ci-deploy-bot
Role: operator

$ hoziron-cli auth whoami --json
{
  "identity": "ci-deploy-bot",
  "role": "operator",
  "key_id": "key-a1b2c3d4"
}

Top-Level Session Commands (OIDC)

Separate from the auth subcommand group, two top-level commands manage an OIDC device-code login session for the active context:

Command	Description
`hoziron-cli login`	Log in via OIDC device-code flow (caches a token for the active context)
`hoziron-cli logout`	Clear the cached OIDC login for the active context

Both only work on a context configured with --auth oidc --issuer <url> --client-id <id> (see context.md); login/logout on any other auth mode fails with a clear error telling you to reconfigure the context.

Top-level hoziron-cli whoami is not a separate implementation — it is a literal alias for hoziron-cli auth whoami (see above): both call GET /auth/whoami and print the same Identity: ... / Role: ... (or --json) output, for whichever credential the active context actually resolves (API key, static token, or OIDC token).

$ hoziron-cli login
Logged in to context 'production' as theo@hoziron.com

# Wrong auth mode for this context
$ hoziron-cli --context local login
Error: Context 'local' has auth_mode = 'none', not 'oidc'. Update it with:
hoziron-cli context add ... --auth oidc --issuer <issuer> --client-id <id>

hoziron-cli logout

$ hoziron-cli logout
Logged out of context 'production'.

# No cached session
$ hoziron-cli logout
No cached login found for context 'production'.

hoziron-cli whoami

$ hoziron-cli whoami
Identity: theo@hoziron.com
Role: operator

$ hoziron-cli whoami --json
{"identity": "theo@hoziron.com", "role": "operator"}

Using API Keys

With the CLI (remote contexts)

# Store key in environment
export HOZIRON_STAGING_KEY="hzn_sk_a1b2c3d4..."

# Add context with key
hoziron-cli context add staging --url https://hoziron.staging.internal --auth local --api-key-env HOZIRON_STAGING_KEY

With curl (API access)

curl -H "Authorization: Bearer hzn_sk_a1b2c3d4..." \
  https://hoziron.staging.internal/agents