agent-auth-cli
/agent-auth-cli
Use the Agent Auth CLI (auth-agent) to discover providers, connect agents, manage capabilities, and execute operations. Use when the user wants to interact with an Agent Auth provider from the terminal, authenticate an agent, execute capabilities, or manage agent connections.
- Author
- better-auth ↗
- Repository
- agent-auth ↗
- Licence
- MIT
- Last repository change
- 09.07.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 9
No signals detected. Repository changed on 09.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use the Agent Auth CLI (auth-agent) to discover providers, connect agents, manage capabilities, and execute operations. Use when the user wants to interact with an Agent Auth provider from the terminal, authenticate an agent, execute capabilities, or manage agent connections.
Original author description
Use the Agent Auth CLI (auth-agent) to discover providers, connect agents, manage capabilities, and execute operations. Use when the user wants to interact with an Agent Auth provider from the terminal, authenticate an agent, execute capabilities, or manage agent connections.
How it works
- Binary
- Workflow
- Global Flags
- Important Rules
- Storage
SKILL.md preview
---
name: agent-auth-cli
description: Use the Agent Auth CLI (auth-agent) to discover providers, connect agents, manage capabilities, and execute operations. Use when the user wants to interact with an Agent Auth provider from the terminal, authenticate an agent, execute capabilities, or manage agent connections.
---
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
auth-agent request <agent-id> \
--capabilities admin_panel \
--constraints '{"admin_panel":{"scope":{"in":["read","write"]}}}' \
--reason "Need admin access for deployment"
```
### 7. Lifecycle management
```bash
# 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
```bash
# 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
```bash
auth-agent enroll-host --provider https://api.example.com --token <enrollment-token> --name "My Device"
```
### 10. Sign JWTs manually
```bash
# 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
| Flag | Env var | Description |
| ----------------------- | -------------------------- | -------------------------------------------- |
| `--storage-dir <path>` | `AGENT_AUTH_STORAGE_DIR` | Storage directory (default: `~/.agent-auth`) |
| `--directory-url <url>` | `AGENT_AUTH_DIRECTORY_URL` | Directory URL for provider search |
| `--host-name <name>` | `AGENT_AUTH_HOST_NAME` | Host name for identification |
| `--no-browser` | `AGENT_AUTH_NO_BROWSER=1` | Suppress browser opening for approval URLs |
| `--url <urls...>` | `AGENT_AUTH_URLS` | Provider URLs to auto-discover at startup |
## 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
Versions
The database has no other skills named agent-auth-cli.
Database snapshot: 13.11.2026 · package version 192423e1996d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100agent-auth-mcp
Use the Agent Auth MCP tools to discover providers, connect agents, manage capabilities, and execute operations through the MCP protocol. Use when working inside an MCP-enabled environment (Cursor, Claude Code, etc.) and need to authenticate agents, execute capabilities, or… - 100agent-auth-connectors
Reliable workflow for using Agent Auth connector capabilities (Gmail and any other provider exposed through the agent-auth tools) — discovering capabilities, connecting an agent per provider, scoping grants with constraints, executing calls, and decoding failure codes. Use… - 100auth-md
Generate, validate, and explain `auth.md` files — the open protocol for AI agent registration. Use when making apps agent-ready, generating Protected Resource Metadata (RFC 9728), validating auth.md files, or implementing agent registration endpoints. Triggers on "auth.md",… - 100three-ws-mcp
Operate three.ws through its hosted MCP servers - connect them, pick the right server and tool, resolve which agent a request is about, read before writing, and treat every fund-moving or irreversible tool as preview, confirm, execute, report. Use when the model has three.ws MCP… - 95agent-management
Create, manage, and orchestrate AI agents using the AI Maestro CLI. Use when the user asks to "create agent", "list agents", "delete agent", "hibernate agent", "wake agent", "install plugin", "show agent", "restart agent", or any agent lifecycle management task. - 100forgetful-cli-setup
Set up the Forgetful CLI and connect from a terminal — install, local or remote mode, auth, and verification. Use when connecting a human or headless agent via shell, wiring CI with token auth, or operating a local server (serve, database selection, feature flags, re-embedding).…