---
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…
---

# 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…

# agent-auth-cliby better-auth
Use the Agent Auth CLI (auth-agent) to discover providers, connect agents, manage capabilities, and execute operations. Use when the user wants to interact…

`npx skills add https://github.com/better-auth/agent-auth --skill agent-auth-cli`Download ZIPGitHub

## 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 [email&#160;protected]
`
```

* 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

FlagEnv varDescription`--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

## More skills from better-auth
agent-auth-mcpby better-authUse the Agent Auth MCP tools to discover providers, connect agents, manage capabilities, and execute operations through the MCP protocol. Use when working…better-iconsby better-authSearch and retrieve SVGs from 200+ icon libraries with CLI and MCP server integration. Supports searching across major collections (Lucide, Material Design Icons, Heroicons, Tabler, and 200+ more) with filtering by prefix and result limits CLI commands for searching icons, downloading batches as SVG files, and retrieving individual icons with color and size customization MCP server tools for AI agents including smart recommendations, similarity matching, project scanning, and batch icon...better-auth-best-practicesby better-authComplete Better Auth server and client setup with database adapters, session management, plugins, and security configuration. Covers full workflow from installation through database migration, environment variable setup, and route handler creation across multiple frameworks Supports multiple database adapters (Prisma, Drizzle, MongoDB, direct connections) with critical guidance on model vs. table naming conventions Includes session storage strategies with secondary storage (Redis/KV), cookie...create-auth-skillby better-authScaffold and implement authentication in TypeScript/JavaScript apps with Better Auth framework detection, database adapter setup, and OAuth integration. Detects frameworks (Next.js, SvelteKit, Nuxt, Astro, Express, Hono), databases (Prisma, Drizzle, MongoDB, raw drivers), and existing auth libraries through project scanning Supports email/password, OAuth (Google, GitHub, Apple, Microsoft, Discord, Twitter), magic links, passkeys, and phone authentication with configurable email verification...Email & Password Best Practicesby better-authemail-&-password-best-practices — an installable skill for AI agents, published by better-auth/skills.email-and-password-best-practicesby better-authEmail verification, password reset flows, and customizable password policies for Better Auth. Supports email verification with optional enforcement to block sign-in until verified, plus configurable token expiration and single-use reset tokens Password reset flows with built-in security: background email sending, timing attack prevention, dummy operations on invalid requests, and optional session revocation on reset Configurable password length limits (default 8–256 characters) and custom...organization-best-practicesby better-authMulti-tenant organization setup with member management, role-based access control, and team support via Better Auth. Configure organizations with customizable creation rules, membership limits, and ownership constraints; creators automatically receive the owner role Manage members and invitations with email delivery, expiration windows, and shareable invitation URLs; support multiple roles per member Define custom roles and permissions with dynamic access control; check permissions...two-factor-authentication-best-practicesby better-authMulti-factor authentication with TOTP, OTP, backup codes, and trusted device management for Better Auth. Supports three verification methods: authenticator apps (TOTP with QR codes), email/SMS codes (OTP), and single-use backup codes Handles complete 2FA sign-in flows with automatic session management, temporary 2FA cookies, and trusted device tracking with configurable expiration Built-in security features including rate limiting (3 requests per 10 seconds), encryption at rest for secrets...

---

**Source**: https://github.com/better-auth/agent-auth/tree/HEAD/skills/agent-auth-cli
**Author**: better-auth
**Discovered via**: mcpservers.org