# Reference

The Bindplane CLI provides a comprehensive set of commands for managing agents, resources, configurations, users, organizations, and more. This reference covers all available commands and their usage.

***

### Getting Started

#### Basic Usage

```bash
bindplane [command] [flags]
```

#### Help

Get help for any command:

```bash
bindplane <command> --help
```

#### Version Information

```bash
bindplane version
```

Displays both server and client version details.

***

### Core Commands

#### `init` / `initialize`

Initialize a Bindplane installation.

| Command        | Description                                  | Usage                    |
| -------------- | -------------------------------------------- | ------------------------ |
| `init server`  | Initialize a new server installation         | `bindplane init server`  |
| `init client`  | Initialize a new client installation         | `bindplane init client`  |
| `init ldap`    | Initialize and migrate to LDAP configuration | `bindplane init ldap`    |
| `init auth`    | Initialize and migrate authentication        | `bindplane init auth`    |
| `init license` | Set license key in configuration             | `bindplane init license` |

#### `serve`

Start the Bindplane server.

```bash
bindplane serve [--force-console-color] [--skip-seed]
```

**Flags:**

* `--force-console-color`: Force colored output
* `--skip-seed`: Do not seed resource types on startup

***

### Resource Management

#### `get`

Display resources and their details.

**Syntax:**

```bash
bindplane get <resource-type> [id/name] [flags]
```

**Available Resource Types:**

* `agents` / `agent` - Agent instances
* `agent-types` / `agent-type` - Agent type definitions
* `agent-versions` / `agent-version` - Agent version definitions
* `configurations` / `configuration` / `configs` / `config` - Agent configurations
* `sources` / `source` - Data sources
* `source-types` / `source-type` - Source type definitions
* `processors` / `processor` - Data processors
* `processor-types` / `processor-type` - Processor type definitions
* `destinations` / `destination` - Data destinations
* `destination-types` / `destination-type` - Destination type definitions
* `extensions` / `extension` - Extensions
* `extension-types` / `extension-type` - Extension type definitions
* `connectors` / `connector` - Connectors
* `connector-types` / `connector-type` - Connector type definitions
* `recommendation-types` / `recommendation-type` - Recommendation types
* `available-components` / `available-component` - Available components
* `rollouts` / `rollout` - Configuration rollouts
* `organizations` / `organization` - Organizations
* `accounts` / `account` - Projects/accounts
* `users` / `user` - Users
* `audit-events` / `audit-event` - Audit events
* `organization-accounts` / `organization-account` - Organization accounts
* `organization-users` / `organization-user` - Organization users
* `recordings` / `recording` - Recordings
* `fleets` / `fleet` - Agent fleets
* `resources` - All resources

**Common Flags:**

* `--history`: Show resource history (where supported)
* `--export`: Export resource in importable format
* `--selector`: Filter by label selector
* `--query`: Search query
* `--offset`, `--limit`, `--sort`: For paging and sorting
* `--show-all-labels`: Show all labels for agents

**Examples:**

```bash
# List all agents
bindplane get agents

# Get specific agent
bindplane get agent <agent-id>

# Get configurations with filtering
bindplane get configurations --selector "platform=linux" # Defined selectors (key-value pairs)
bindplane get configurations --query "linux" # Search query

# Export configuration to YAML
bindplane get configuration my-config --export --output yaml
```

#### `apply`

**Create or update (upsert) any resource in Bindplane** from files or stdin. The `apply` command is the primary method for managing all Bindplane resources. It will create new resources if they don't exist, or update existing resources if they do.

**Syntax:**

```bash
bindplane apply -f <file1.yaml> [file2.yaml ...]
bindplane apply <directory>/**/*
bindplane apply -
```

**Flags:**

* `-f, --file`: Path(s) to YAML file(s) specifying resources

**Supported Resource Types:**

The `apply` command works with all Bindplane resources:

* `agents` / `agent` - Agent instances
* `agent-types` / `agent-type` - Agent type definitions
* `agent-versions` / `agent-version` - Agent version definitions
* `configurations` / `configuration` / `configs` / `config` - Agent configurations
* `sources` / `source` - Data sources
* `source-types` / `source-type` - Source type definitions
* `processors` / `processor` - Data processors
* `processor-types` / `processor-type` - Processor type definitions
* `destinations` / `destination` - Data destinations
* `destination-types` / `destination-type` - Destination type definitions
* `extensions` / `extension` - Extensions
* `extension-types` / `extension-type` - Extension type definitions
* `connectors` / `connector` - Connectors
* `connector-types` / `connector-type` - Connector type definitions
* `organizations` / `organization` - Organizations
* `accounts` / `account` - Projects/accounts
* `users` / `user` - Users
* `fleets` / `fleet` - Agent fleets

**Examples:**

```bash
# Create or update a configuration
bindplane apply -f my-config.yaml

# Apply multiple resource files
bindplane apply configs/*.yaml

# Apply from stdin
cat config.yaml | bindplane apply -

# Apply all YAML files in a directory
bindplane apply ./resources/**/*.yaml
```

**Important Notes:**

* **Upsert Behavior**: `apply` will create new resources if they don't exist, or update existing resources if they do
* **Idempotent**: You can safely run `apply` multiple times on the same resources
* **File Format**: Resources must be specified in YAML format
* **Resource Identification**: Resources are identified by their `name` field in the YAML

#### `delete`

Delete resources.

```bash
bindplane delete -f <file.yaml>
bindplane delete <resource-type> <name> [--force]
bindplane delete agent <agent-ids> [--selector <label-query>] [--query <query>]
bindplane delete organization <id> [--force]
```

**Flags:**

* `-f, --file`: Path to YAML file specifying resources
* `--selector`: Label selector for filtering
* `--query`: Query for filtering
* `--force`: Force deletion with no checks

**Supported Resource Types:**

* `agent`
* `agent-type`
* `agent-version`
* `configuration`
* `source`
* `source-type`
* `processor`
* `processor-type`
* `connector`
* `connector-type`
* `destination`
* `destination-type`
* `extension`
* `extension-type`
* `recommendation-type`
* `project`
* `user`
* `recording`
* `fleet`
* `organization`

**Examples:**

```bash
# Delete by name
bindplane delete configuration my-config

# Delete agents by selector
bindplane delete agent --selector "environment=staging"

# Delete from file
bindplane delete -f resources-to-delete.yaml
```

#### `copy`

Make a copy of a resource.

```bash
bindplane copy configuration <source-config> <destination-config>
```

**Aliases:** `cp`

**Examples:**

```bash
bindplane copy config my-config my-config-copy
```

***

### Agent Version Management

#### `update`

Update existing agents.

```bash
bindplane update agent <id> [--version <version>]
```

**Aliases:** `upgrade`

**Flags:**

* `--version`: Version of the agent to install (default: "latest")

**Examples:**

```bash
# Update to latest version
bindplane update agent agent-123

# Update to specific version
bindplane update update agent agent-123 --version v1.30.0
```

#### `sync`

Synchronize agent-versions from GitHub.

```bash
bindplane sync agent-version [--agent-type <type>] [--version <version>] [--all]
```

**Flags:**

* `--agent-type`: Agent type to sync (default: "observiq-otel-collector")
* `--version`: Version to sync (default: "latest")
* `--all`: Sync all versions

**Examples:**

```bash
# Sync latest version
bindplane sync agent-version

# Sync specific version
bindplane sync agent-version --version v1.30.0

# Sync all versions
bindplane sync agent-version --all
```

#### `upload`

Upload offline agent upgrade packages.

```bash
bindplane upload agent-upgrade <file> [--version <version>]
```

**Examples:**

```bash
# Upload with auto-detected version
bindplane upload agent-upgrade observiq-otel-collector-v1.30.0-artifacts.tar.gz

# Upload with specified version
bindplane upload agent-upgrade package.tar.gz --version v1.30.0
```

***

### Agent Configuration Management

#### `rollout`

Manage configuration rollouts.

<table><thead><tr><th width="156.33203125">Command</th><th width="158.65234375">Description</th><th>Usage</th></tr></thead><tbody><tr><td><code>rollout update</code></td><td>Update a rollout</td><td><code>bindplane rollout update [configuration]</code></td></tr><tr><td><code>rollout start</code></td><td>Start a rollout</td><td><code>bindplane rollout start &#x3C;configuration> [flags]</code></td></tr><tr><td><code>rollout pause</code></td><td>Pause a rollout</td><td><code>bindplane rollout pause &#x3C;configuration></code></td></tr><tr><td><code>rollout resume</code></td><td>Resume a rollout</td><td><code>bindplane rollout resume &#x3C;configuration></code></td></tr><tr><td><code>rollout status</code></td><td>Get rollout status</td><td><code>bindplane rollout status &#x3C;configuration></code></td></tr></tbody></table>

**Start Flags:**

* `--all`: Start rollout for every configuration
* `--max-errors`: Maximum errors before pausing
* `--initial`: Initial number of agents
* `--multiplier`: Multiplier for agent count
* `--max`: Maximum number of agents

**Examples:**

```bash
# Start rollout with options
bindplane rollout start my-config --max-errors 5 --initial 10 --multiplier 2 --max 100

# Start all rollouts
bindplane rollout start --all

# Check status
bindplane rollout status my-config
```

***

### Configuration Migration

#### `migrate-configuration chronicle`

Convert Chronicle Forwarder `.conf` files into Bindplane configurations and destinations.

```bash
bindplane migrate-configuration chronicle [-f <path>] [--name <name>] [-]
```

**Flags:**

* `-f, --file`: Path to a single `.conf` file, a directory, or `-` for stdin.
* `-n, --name`: Name for the resulting configuration. Required for stdin. Optional for single-file input. Not allowed for directory input.

**Examples:**

```bash
# Migrate a single forwarder config
bindplane migrate-configuration chronicle -f host1.conf

# Migrate all .conf files in a directory
bindplane migrate-configuration chronicle -f ./configs/

# Migrate from stdin
fetch-config.sh | bindplane migrate-configuration chronicle --name host1 -
```

**Important Notes:**

* **Naming**: Configuration names are derived from the filename. Destinations are named `<config-name>-dest-<index>`.
* **Two-file configs**: If `<stem>_auth.conf` is found alongside `<stem>.conf`, both are merged automatically.
* **Directory layout**: Supports a flat directory of `.conf` files or one level of subdirectories. Deeper nesting is ignored.
* **Conflicts**: The command errors and skips any config whose name conflicts with an existing configuration or destination. There is no overwrite flag. Delete the conflicting resource before retrying.

***

### Project & Organization Management

#### `create`

Create new projects or organizations.

```bash
bindplane create project <name>
bindplane create organization <organization-name>
```

**Examples:**

```bash
bindplane create project my-project
bindplane create organization my-org
```

***

{% hint style="info" %}
Run `bindplane get users` to list the IDs of the users in your project
{% endhint %}

#### `add`

Add users to a Bindplane project.

```bash
bindplane add user --email <email> --name <username> [--create]
```

**Flags:**

* `--email`: Email address of the user
* `--name`: Username
* `--create`: Create the user if necessary

**Examples:**

```bash
bindplane add user --email user@example.com --name username --create
```

#### `demote-org-admin`

Demote a user from the organization admin role.

```bash
bindplane user demote-org-admin <userID>
```

#### `promote-org-admin`

Promote a user to the organization admin role.

```bash
bindplane user promote-org-admin <userID>
```

#### `remove-from-org`

Remove a user from your organization. Also removes the user from all projects within the organization.

```bash
bindplane user remove-from-org <userID>
```

#### `set-project-role`

Modify the role of user in your project.

```bash
bindplane user set-project-role <userID> --role <role>
```

**Flags:**

* `--role`: Required. The project role to set for the user. Must be one of `admin` , `user` , or `viewer` .

**Examples:**

```bash
bindplane user set-project-role 01JQ4XJ7XDD6E0A7PCPEEWEBWJ --role admin
bindplane user set-project-role 01JQ4XJ7XDD6E0A7PCPEEWEBWJ --role user
bindplane user set-project-role 01JQ4XJ7XDD6E0A7PCPEEWEBWJ --role viewer
```

***

### System Administration

#### `admin`

Administrator commands for database maintenance.

<table><thead><tr><th width="200.6484375">Command</th><th width="163.24609375">Description</th><th>Usage</th></tr></thead><tbody><tr><td><code>admin vacuum-stats</code></td><td>Display vacuum statistics</td><td><code>bindplane admin vacuum-stats</code></td></tr><tr><td><code>admin vacuum-analyze</code></td><td>Vacuum and analyze database</td><td><code>bindplane admin vacuum-analyze [-y] [-f]</code></td></tr></tbody></table>

**Vacuum Flags:**

* `-y, --accept`: Automatically accept the prompt
* `-f, --full`: Perform a full vacuum

**Examples:**

```bash
# Show vacuum stats
bindplane admin vacuum-stats

# Perform vacuum with confirmation
bindplane admin vacuum-analyze

# Perform full vacuum without confirmation
bindplane admin vacuum-analyze -y -f
```

#### `migrate`

Perform database migrations.

```bash
bindplane migrate [version] [-y]
```

**Flags:**

* `version`: Specific version to migrate to
* `-y, --accept`: Automatically accept the prompt

**Examples:**

```bash
# Migrate to latest
bindplane migrate

# Migrate to specific version
bindplane migrate v1.30.0

# Non-interactive migration
bindplane migrate -y
```

#### `secret`

Manage secret keys for the current project.

<table><thead><tr><th width="169.91015625">Command</th><th width="192.3984375">Description</th><th>Usage</th></tr></thead><tbody><tr><td><code>secret get</code></td><td>Get secret keys</td><td><code>bindplane secret get</code></td></tr><tr><td><code>secret add</code></td><td>Add a secret key</td><td><code>bindplane secret add</code></td></tr><tr><td><code>secret delete</code></td><td>Delete a secret key</td><td><code>bindplane secret delete &#x3C;key></code></td></tr><tr><td><code>secret default</code></td><td>Set default secret key</td><td><code>bindplane secret default &#x3C;key></code></td></tr></tbody></table>

**Examples:**

```bash
# List all secret keys
bindplane secret get

# Add new secret key
bindplane secret add

# Set default key
bindplane secret default my-key
```

***

### Development & Utilities

#### `profile`

Manage Bindplane CLI profiles.

<table><thead><tr><th width="166.8828125">Command</th><th width="211.6953125">Description</th><th>Usage</th></tr></thead><tbody><tr><td><code>profile get</code></td><td>Get profile details</td><td><code>bindplane profile get [name]</code></td></tr><tr><td><code>profile set</code></td><td>Set profile details</td><td><code>bindplane profile set [name]</code></td></tr><tr><td><code>profile create</code></td><td>Create a new profile</td><td><code>bindplane profile create &#x3C;name></code></td></tr><tr><td><code>profile delete</code></td><td>Delete a profile</td><td><code>bindplane profile delete &#x3C;name></code></td></tr><tr><td><code>profile list</code></td><td>List all profiles</td><td><code>bindplane profile list</code></td></tr><tr><td><code>profile use</code></td><td>Use a profile</td><td><code>bindplane profile use &#x3C;name></code></td></tr><tr><td><code>profile current</code></td><td>Show current profile</td><td><code>bindplane profile current</code></td></tr></tbody></table>

**Examples:**

```bash
# Create and use a new profile
bindplane profile create production
bindplane profile use production

# List all profiles
bindplane profile list

# Get current profile details
bindplane profile get
```

#### `label`

Manage resource labels (currently agents only).

```bash
bindplane label agent <id> [key=value ...] [flags]
```

**Flags:**

* `--list`: List labels for agent
* `--overwrite`: Overwrite existing labels
* `--selector`: Filter agents by label
* `--query`: Filter agents by query

**Examples:**

```bash
# List agent labels
bindplane label agent agent-123 --list

# Add labels
bindplane label agent agent-123 environment=production region=us-west

# Remove label (set to empty)
bindplane label agent agent-123 old-label-

# Label multiple agents by selector
bindplane label agent --selector "environment=staging" team=backend
```

***

### Command Categories Summary

| Category           | Commands                         |
| ------------------ | -------------------------------- |
| **Core**           | `init`, `serve`, `version`       |
| **Resources**      | `get`, `apply`, `delete`, `copy` |
| **Agents**         | `update`, `sync`, `upload`       |
| **Configurations** | `rollout`                        |
| **Users & Orgs**   | `create`, `add`                  |
| **Administration** | `admin`, `migrate`, `secret`     |
| **Utilities**      | `profile`, `label`               |

***

### Getting Help

For detailed help on any command:

```bash
bindplane <command> --help
```

For help on subcommands:

```bash
bindplane <command> <subcommand> --help
```

***

### Tips & Best Practices

1. **Use profiles** to manage different environments (dev, staging, production)
2. **Use selectors and queries** to filter resources efficiently
3. **Export configurations** before making changes: `bindplane get configuration <name> --export > backup.yaml`
4. **Use rollouts** for safe configuration deployments
5. **Check resource status** before deleting: `bindplane get <resource-type> <name>`
6. **Use the `--force` flag** carefully, especially with delete operations

***

*This reference covers all available Bindplane CLI commands. For more detailed information about specific features or advanced usage, join the Bindplane Slack Community to get help from the team.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/cli-and-api/cli/reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.