CLI reference

The agent-auth command runs the server and talks to it. Every command reads its settings from flags or from the environment variables listed below. This page shows the output of agent-auth --help.

agent-auth: scoped, expiring, auditable credentials for AI agents

Usage: agent-auth <command> [options]

Server
  serve                      Start the REST server
      --port <n>             Port (default 8787, env AGENT_AUTH_PORT)
      --host <addr>          Bind address (default 127.0.0.1, env AGENT_AUTH_HOST)
      --db <path>            SQLite file (default ./data/agent-auth.db, env AGENT_AUTH_DB)
      --key <path>           Signing key file (default ./data/signing-key.pem, env AGENT_AUTH_KEY)
      --issuer <url>         Issuer URL placed in tokens (env AGENT_AUTH_ISSUER)

Principal commands (need AGENT_AUTH_ADMIN_TOKEN)
  grant                      Delegate scopes to an agent and print its token
      --principal <id>       Who delegates (required)
      --agent <id>           Who receives the grant (required)
      --scope <scope>        Scope, repeatable (required)
      --ttl <dur>            Lifetime such as 15m, 1h, 7d (default 1h)
      --max-uses <n>         Maximum number of allowed uses
  revoke <jti>               Revoke a token and everything derived from it
  revoke --grant <id>        Revoke a whole grant
  approvals [--status s]     List approval requests (default: pending)
  approve <id> | deny <id>   Decide a pending approval
  audit log                  Print audit entries
  audit verify               Verify the audit hash chain
      --db <path>            Read the SQLite file directly instead of the server
      --head <hash>          Fail unless this previously anchored head is in the chain

Agent commands
  attenuate                  Derive a narrower token from --token
      --scope <scope>        Scope, repeatable (required)
      --ttl <dur>            Lifetime, capped at the parent's expiry
      --max-uses <n>         Maximum number of allowed uses
      --agent <id>           Sub-agent that receives the token
  check                      Ask whether --token permits a request (consumes a use)
      --action <a>           Concrete action, for example gmail:send (required)
      --resource <r>         Resource, for example acme/widgets
      --param <k=v>          Request parameter, repeatable
      --amount <amt>         Amount, for example 20USD
      --approval <id>        Approved approval id to redeem
      --dry-run              Evaluate without consuming a use
  inspect                    Decode --token and show its live status
  revoke --token <t>         Revoke the presented token and its descendants

Global options
  --url <url>                Server URL (default http://127.0.0.1:8787, env AGENT_AUTH_URL)
  --token <t>                Agent token, or @file, or - for stdin (env AGENT_AUTH_TOKEN)
  --json                     Print raw JSON
  -q, --quiet                Print only the essential value (for example the token)
  -h, --help                 Show this help
  -v, --version              Print the version

Exit codes: 0 success or allow, 1 error, 3 deny, 4 approval required.

Exit codes

Code	Meaning
0	Success, or the request is allowed
1	Error, including usage errors and a tampered audit chain
3	The request is denied, or the token is inactive
4	The request needs a human approval