> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference: Commands, Flags & Configuration

> Full reference for the Buckle command-line tool: installation, every command with flags, environment variables, and configuration.

The `buckle` CLI lets you manage your Buckle instance from the terminal. Create agents, add secrets, configure access, all with JSON output that AI agents can parse and act on.

**GitHub:** [github.com/trybuckle/buckle-cli](https://github.com/trybuckle/buckle-cli)

## Why a CLI for managing Buckle?

The dashboard is great for humans. But when an AI agent needs to set up its own environment (create its identity, register the secrets it needs, check its current access), it shouldn't need a human clicking through a UI.

The `buckle` CLI gives agents (and the frameworks that orchestrate them) a programmatic interface to manage the Buckle server. An agent orchestrator can spin up a new agent, assign it credentials for specific services, and configure rules, all in a single script, no browser required.

This is especially useful for:

* Agent bootstrapping, where an orchestrator creates an agent identity and assigns secrets before the agent starts working
* Dynamic provisioning: spin up short-lived agents with scoped access for specific tasks, then clean up after
* CI/CD pipelines that automate agent and secret management as part of your deployment
* Self-healing agents that detect a missing credential, check their own status, and request what they need

## Install

```bash theme={null}
curl -fsSL buckle.dev/cli/install | sh
```

Or download from [GitHub Releases](https://github.com/trybuckle/buckle-cli/releases), or build from source:

```bash theme={null}
go install github.com/trybuckle/buckle-cli/cmd/buckle@latest
```

## Quick start

```bash theme={null}
buckle auth login --api-key oc_...
buckle agents list
buckle secrets list
buckle agents create --name "My Agent" --identifier my-agent
```

## Commands

### Run

Wrap a coding agent process with Buckle gateway access. See the [Coding Agents guide](/docs/guides/coding-agents.md) for the full walkthrough.

```bash theme={null}
buckle run -- claude                               # Launch Claude Code with gateway access
buckle run --agent my-agent -- cursor              # Use a specific agent identity
buckle run --dry-run -- claude                     # Preview config without launching
buckle run --gateway localhost:10255 -- claude     # Override gateway address
buckle run --no-ca -- claude                       # Skip CA cert injection
```

The agent identity resolves as `--agent` flag, then `BUCKLE_AGENT`, then `buckle config set agent`, then the project's default agent.

### Projects

Manage projects (isolated workspaces for agents, secrets, and connections). See the [Projects guide](/docs/guides/projects.md) for details.

```bash theme={null}
buckle projects list                                   # List all projects
buckle projects get --id X                             # Get a single project
buckle projects create --name "payments-app"           # Create a new project
buckle projects update --id X --name "new-name"        # Rename a project
buckle projects delete --id X --confirm X              # Delete a project (repeat the ID to confirm)
```

Deleting a project permanently removes all its agents, secrets, connections, grants, and audit logs. `--confirm` must repeat the project ID to prevent accidental deletion. You cannot delete your last remaining project.

Most commands accept `--project` (or `-p`) to target a specific project. Without it, the active project from `buckle config set project` is used, or the default project.

### Agents

Manage agent identities. An agent belongs to a project and uses only the credentials you grant it (see [Agent access](/docs/guides/agent-access.md)).

```bash theme={null}
buckle agents list                                     # List agents in active project
buckle agents list --with-grants                       # Include each agent's grants summary
buckle agents list --project payments-app              # List agents in a specific project
buckle agents get-default                              # Get the default agent
buckle agents set-default --id X                       # Mark an agent as the project default
buckle agents create --name X --identifier Y           # Create a new agent (starts with no grants)
buckle agents delete --id X                            # Delete an agent
buckle agents rename --id X --name Y                   # Rename an agent
buckle agents regenerate-token --id X                  # Regenerate access token
buckle agents credentials --id X                       # Effective view: what the agent can use, and what each credential can do
```

The retired assignment commands (`agents secrets`, `set-secrets`, `set-secret-mode`, `agents connections get|set`) still ship for pre-grants self-hosted servers; updated servers answer `410 Gone` pointing at grants.

### Grants

Attach credentials to agents — the write path for per-agent access. A bare attach grants full access; `--allow`/`--ask` narrow a connection to named tools (ids from `apps permission-definition`). Writes take effect immediately.

```bash theme={null}
buckle agents grants list --id X                       # The agent's grants (connections + secrets)
buckle agents grants attach-connection --id X \
  --connection-id Y                                    # Full access to the connection
buckle agents grants attach-connection --id X \
  --connection-id Y \
  --allow search_messages,get_message \
  --ask send_email                                     # Per-tool: allow freely / require approval; unlisted = blocked
buckle agents grants attach-connection --id X \
  --connection-id Y \
  --json '{"access":"custom","allow":["read_all"],"ask":[]}'   # Raw grant body (XOR with --allow/--ask)
buckle agents grants detach-connection --id X --connection-id Y
buckle agents grants attach-secret --id X --secret-id Z        # Secrets are all-or-nothing
buckle agents grants detach-secret --id X --secret-id Z
buckle apps connections grants --id Y                  # Reverse view: which agents hold a grant for a connection
```

A custom grant must name at least one tool across `--allow` and `--ask` (all-blocked = detach instead), and a tool can't be in both lists — the server rejects either with `422`. `--ask` requires a plan with manual approvals. Grants are the **intent**; `agents credentials` and `apps connections agent-access` show the **effective** result after organization rules apply.

### Secrets

Manage credentials stored in the vault.

```bash theme={null}
buckle secrets list                                    # List secrets in active project
buckle secrets list --project payments-app             # List secrets in a specific project
buckle secrets create --name "Anthropic" --type anthropic \
  --value "$ANTHROPIC_API_KEY" \
  --host-pattern api.anthropic.com                     # Anthropic API key
buckle secrets create --name "OpenAI" --type openai \
  --value "$OPENAI_API_KEY" \
  --host-pattern api.openai.com                        # OpenAI API key
buckle secrets create --name X --type generic \
  --value Y --host-pattern api.example.com \
  --header-name Authorization \
  --value-format "Bearer {value}"                      # Header injection
buckle secrets create --name X --type generic \
  --value Y --host-pattern api.example.com \
  --param-name key                                     # Query param injection
buckle secrets create --name "Codex" --type openai \
  --file ~/.codex/auth.json \
  --host-pattern api.openai.com                        # Read the value from a file
buckle secrets update --id X --value Y                 # Update a secret
buckle secrets delete --id X                           # Delete a secret
```

The `--type` flag accepts `anthropic`, `openai`, or `generic`. For `anthropic` and `openai` types, the gateway handles header injection automatically. For `generic` secrets, you must specify injection flags. `--value` and `--file` are mutually exclusive; use `--file` for multi-line values like Codex's `auth.json`.

When creating or updating a generic secret, the available injection flags are:

| Flag | Description |
| - | - |
| `--header-name` | Inject as an HTTP header (e.g. `Authorization`) |
| `--value-format` | Header value template (default: `{value}`, e.g. `Bearer {value}`) |
| `--param-name` | Inject as a URL query parameter (e.g. `key`) |
| `--param-format` | Param value template (default: `{value}`) |

`--header-name` and `--param-name` are mutually exclusive: each secret injects as either a header or a query parameter, not both.

### Apps

Manage OAuth app connections so the Buckle gateway can handle token exchange on behalf of agents. After configuring an app, use `apps list` to get the [credential stubs docs](/docs/guides/credential-stubs/gmail.md) URL your MCP server needs to start.

```bash theme={null}
buckle apps list                                       # List all apps with config and connection status
buckle apps get --provider gmail                       # Get a single app with setup guidance
buckle apps connections list                           # List app connections
buckle apps connections list --provider github         # Filter by provider
buckle apps connections rename --id X --label "Work"   # Rename a connection
buckle apps connections grants --id X                  # Which agents hold a grant (intent)
buckle apps connections agent-access --id X            # Which agents can reach it, per tool (effective, read-only)
buckle apps disconnect --provider gmail                # Disconnect (errors with the ID list if multiple connections; pass --connection-id)
buckle apps disconnect --provider gmail \
  --connection-id X                                    # Disconnect a specific connection
buckle apps configure --provider gmail --client-id X \
  --client-secret Y                                    # Save OAuth credentials (BYOC)
buckle apps configure --provider github-app \
  --field appId=123 --field appSlug=my-app \
  --field privateKey="$(cat key.pem)"                  # Arbitrary per-app fields
buckle apps remove --provider gmail                    # Remove BYOC credentials
buckle apps config get --provider gmail                # BYOC config status (settings, enabled)
buckle apps config toggle --provider gmail --enabled=false
buckle apps configured                                 # Providers with an enabled config
buckle apps env-defaults                               # Providers with platform default credentials
buckle apps permission-definition --provider github    # Tool catalog for permission rules
```

#### App blocklists

Some apps ship predefined blocklist hosts (e.g. public registries) you can activate; you can also add custom deny rules per app:

```bash theme={null}
buckle apps blocklist list --provider github           # Blocklist state (predefined + custom)
buckle apps blocklist activate --provider github --host-id X
buckle apps blocklist add --provider github --name X --host-pattern uploads.github.com
buckle apps blocklist toggle --provider github --rule-id X --enabled=false
buckle apps blocklist remove --provider github --rule-id X
```

### Policy

Policy rules are authored at the **organization** level — see [Org Policy](#org-policy) below and the [Policy rules guide](/docs/guides/rules.md). At project scope, rules are compiled from [grants](#grants); the one project-scope policy read is the effective reflection:

```bash theme={null}
buckle policy effective-permissions --provider gmail   # Per-tool verdicts for an app (read-only)
```

The project-scope authoring family (`buckle policy rules ...`, `policy default`, `policy publish`, `policy status`) still ships for pre-grants self-hosted servers; updated servers answer `410 Gone` pointing at grants (project access) and `buckle org policy` (organization rules). The even older `buckle rules` family serves servers that predate the policy engine.

### Organization

Organization-scoped commands manage resources that apply across all projects. These mirror the project-level `secrets` and `apps` commands — and carry the full `policy` rule console — at the org level, with no `--project` flag needed. They require the admin or owner role.

#### Org Secrets

```bash theme={null}
buckle org secrets list                                # List all org-scoped secrets
buckle org secrets create --name "Anthropic" --type anthropic \
  --value "$ANTHROPIC_API_KEY" \
  --host-pattern api.anthropic.com                     # Create org secret
buckle org secrets update --id X --value Y             # Update an org secret
buckle org secrets delete --id X                       # Delete an org secret
```

Org secrets use the same `--type`, injection flags (`--header-name`, `--param-name`, etc.), and `--json` override as project-level secrets.

#### Org Policy

```bash theme={null}
buckle org policy rules list [--status published]      # Org rules (draft or enforced)
buckle org policy rules create --name X --action block \
  --targets '[{"kind":"network","hostPattern":"api.github.com"}]'
buckle org policy rules update --id X --enabled=false  # Update a DRAFT org rule
buckle org policy rules delete --id X                  # Delete a DRAFT org rule
buckle org policy rules reorder --ordered-ids '[...]'  # Full id permutation
buckle org policy default get|set --action allow|block # The org Default Rule
buckle org policy publish                              # Publish the org draft
buckle org policy status                               # Staged diff + last publish
```

Org policy rules take `user`/`group` identities via `--identities` (never a specific agent). Requires an org API key with the admin role. The older `buckle org rules` family serves self-hosted servers that predate the policy engine (updated servers answer `410 Gone`).

#### Org Connections

```bash theme={null}
buckle org connections list                            # List all org connections
buckle org connections list --provider github          # Filter by provider
buckle org connections rename --id X --label "Shared"  # Rename a connection
buckle org connections delete --id X                   # Delete a connection
```

#### Org Apps

Manage BYOC (bring your own credentials) app configuration at the org level.

```bash theme={null}
buckle org apps configured                             # List providers with org credentials
buckle org apps get --provider gmail                   # Get config status for a provider
buckle org apps configure --provider gmail \
  --client-id X --client-secret Y                      # Save BYOC credentials
buckle org apps remove --provider gmail                # Remove BYOC credentials
buckle org apps toggle --provider gmail --enabled=true # Enable or disable an app
buckle org apps blocklist list --provider github       # Org-level blocklist (same subcommands as
                                                       # 'buckle apps blocklist')
```

The organization's allow/deny posture is its Default Rule: `buckle org policy default get|set`. (The retired `buckle org settings` family answers `410 Gone` on updated servers.)

### Vaults and counts

```bash theme={null}
buckle vaults list                                     # External vault connections (e.g. 1Password)
buckle counts                                          # Project resource totals (agents, apps, llms, secrets)
```

### Migrate

Move a self-hosted instance's data (secrets and agents) to Buckle Cloud. Policy rules and grants don't travel — they're counted and reported as skipped so you can re-create them on the destination. Run against the self-hosted server; secrets are decrypted server-side and sent directly to Cloud over HTTPS.

```bash theme={null}
buckle migrate --cloud-key oc_your_cloud_key           # Migrate to Buckle Cloud
buckle migrate --cloud-key oc_... --dry-run            # Preview without executing
```

### Auth

Authenticate with the Buckle server.

```bash theme={null}
buckle auth login [--api-key oc_...]                   # Store API key
buckle auth logout                                     # Remove stored API key
buckle auth status                                     # Check current auth state
buckle auth update --name "New Name"                   # Update your display name
buckle auth api-key                                    # Show your current API key
buckle auth regenerate-api-key                         # Regenerate your API key
```

Authentication is only required when the server enforces it. In local/single-user mode, commands work without logging in.

### Config

Read and write configuration values.

```bash theme={null}
buckle config get <key>                                # Read config value
buckle config set <key> <value>                        # Write config value
buckle config set project payments-app                 # Set active project for all commands
buckle config set agent writer-bot                     # Pin this machine to an agent for `buckle run`
```

| Key | Description |
| - | - |
| `api-host` | API base URL (default: `https://api.buckle.dev`) |
| `project` | Active project slug used when no `--project` flag is given |
| `agent` | Agent identifier `buckle run` uses when no `--agent` flag is given |

The `agent` key requires CLI 2.10 or later.

## Output

All output is JSON. Use `--fields` to select specific fields, or `--quiet` to extract a single value:

```bash theme={null}
buckle agents list --quiet id
# "agent_abc123"
# "agent_def456"

buckle agents list --fields id,name,identifier
# [{"id": "agent_abc123", "name": "My Agent", "identifier": "my-agent"}, ...]
```

Agents and scripts can parse responses directly without `jq` or string manipulation.

List commands return at most 20 results by default; pass `--max` to raise (or lower) the cap.

## Environment variables

| Variable | Description |
| - | - |
| `BUCKLE_API_KEY` | API key (overrides stored key) |
| `BUCKLE_API_HOST` | API base URL (default: `https://api.buckle.dev`) |
| `BUCKLE_PROJECT` | Active project slug (overrides `buckle config set project`) |
| `BUCKLE_AGENT` | Agent identifier for `buckle run` (overrides `buckle config set agent`) |
| `BUCKLE_ENV` | `dev` or `production` |

## Example: agent orchestrator bootstrapping

A common pattern is an orchestrator that provisions agents before they start working:

```bash theme={null}
# Create a project for this workflow
buckle projects create --name "email-workflow"
buckle config set project email-workflow

# Add the secret the agent needs
SECRET=$(buckle secrets create --name "Gmail" --type generic \
  --value "$GMAIL_KEY" --host-pattern "*.googleapis.com" \
  --header-name Authorization --value-format "Bearer {value}" | jq -r .id)

# Create the agent (it starts with no grants)
AGENT=$(buckle agents create --name "email-agent" --identifier email-agent | jq -r .id)

# Grant it the secret — without this, the gateway injects nothing
buckle agents grants attach-secret --id "$AGENT" --secret-id "$SECRET"

# Get its access token
TOKEN=$(buckle agents regenerate-token --id "$AGENT" | jq -r .accessToken)

# Pass the token to the agent container
docker run -e HTTPS_PROXY=http://buckle:10255 \
  -e PROXY_AUTH="$TOKEN" \
  my-email-agent:latest
```

The agent uses exactly the credentials granted to it, enforced by the gateway under any organization [rules](/docs/guides/rules.md) you've configured. No hardcoded keys, no broad access.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.