agent-auth-cli

Agent Auth CLI

You have access to the auth-agent CLI for interacting with Agent Auth providers. Always prefer using the CLI for any agent authentication operations rather than making raw HTTP requests or writing custom code.

Binary

The CLI binary is auth-agent (package: @auth/agent-cli). If not installed globally, run via npx @auth/agent-cli.

Workflow

Follow this order when working with a provider:

1. Discover or find a provider

# If you have the provider URL
auth-agent discover https://api.example.com
 
# If you need to search by intent
auth-agent search "deploy web apps"
 
# List already-known providers
auth-agent providers

• discover fetches the /.well-known/agent-configuration document and caches the provider.
• search queries the directory and returns matching providers.
• Always discover or search first before connecting.

2. Explore capabilities

# List all capabilities for a provider
auth-agent capabilities --provider https://api.example.com
 
# Filter by query
auth-agent capabilities --provider https://api.example.com --query "transfer"
 
# Get full definition with input schema
auth-agent describe transfer_money --provider https://api.example.com

• Always run describe before executing a capability to understand the required input schema and constraints.
• If connected, pass --agent-id <id> to see which capabilities are granted.

3. Connect an agent

# Basic connection with specific capabilities
auth-agent connect --provider https://api.example.com \
  --capabilities read_data transfer_money \
  --name my-agent
 
# With constraints on capability arguments
auth-agent connect --provider https://api.example.com \
  --capabilities read_data transfer_money \
  --constraints '{"transfer_money":{"amount":{"max":1000}}}' \
  --name constrained-agent
 
# Autonomous mode (no user association)
auth-agent connect --provider https://api.example.com \
  --capabilities read_data \
  --mode autonomous
 
# With CIBA approval (backchannel, sends notification to user)
auth-agent connect --provider https://api.example.com \
  --capabilities read_data \
  --preferred-method ciba \
  --login-hint user@example.com

• Save the returned agent_id — you need it for all subsequent operations.
• If approval is required, the CLI opens the browser or prints the approval URL. Pass --no-browser to suppress browser opening.
• Use --force-new to create a new connection even if one exists.

4. Check status

auth-agent status <agent-id>

• Shows agent status (pending_approval, active, expired, revoked), granted capabilities, and constraints.
• Run this after connecting to confirm the agent was approved.

5. Execute capabilities

auth-agent execute <agent-id> transfer_money \
  --args '{"amount": 50, "to": "alice"}'

• The --args flag takes a JSON string matching the capability's input schema.
• Always describe the capability first to know the required arguments.

6. Request additional capabilities

auth-agent request <agent-id> \
  --capabilities admin_panel \
  --constraints '{"admin_panel":{"scope":{"in":["read","write"]}}}' \
  --reason "Need admin access for deployment"

7. Lifecycle management

# Disconnect (revoke) an agent
auth-agent disconnect <agent-id>
 
# Reactivate an expired agent
auth-agent reactivate <agent-id>
 
# View stored connection details
auth-agent connection <agent-id>
 
# List all connections for a provider
auth-agent connections <issuer-url>

8. Key rotation

# Rotate an agent's keypair
auth-agent rotate-agent-key <agent-id>
 
# Rotate the host keypair for a provider
auth-agent rotate-host-key <issuer-url>

9. Host enrollment

auth-agent enroll-host --provider https://api.example.com --token <enrollment-token> --name "My Device"

10. Sign JWTs manually

# Sign an agent JWT (for use with external HTTP calls)
auth-agent sign <agent-id>
 
# Scope to specific capabilities
auth-agent sign <agent-id> --capabilities transfer_money read_data

Global Flags

Important Rules

• Never make raw HTTP requests to Agent Auth endpoints. Always use the CLI.
• Always discover before connecting. The CLI needs the provider's configuration cached locally.
• Always describe before executing. Check the input schema so you pass correct arguments.
• Check status after connecting. The agent may require user approval before it becomes active.
• Store agent IDs. You need them for execute, status, request, disconnect, and all other operations.
• Use constraints when connecting to limit what the agent can do — this is a security best practice.
• Set AGENT_AUTH_ENCRYPTION_KEY in production to encrypt private keys stored in ~/.agent-auth/.

Storage

Connections, keys, and provider configs are stored in ~/.agent-auth/ by default:

• host.json — host identity and keypair
• agents/<agent-id>.json — agent connections
• providers/<encoded-issuer>.json — cached provider configurations