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

• 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

• 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

• 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

• 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

7. Lifecycle management

8. Key rotation

9. Host enrollment

10. Sign JWTs manually

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