# CLI & API

The Bindplane CLI and REST API provide programmatic access to all Bindplane functionality, enabling automation, integration, and advanced management of your telemetry infrastructure.

{% hint style="info" %}
**Availability**

📘 The CLI is available for all Bindplane plans.

📘 API access is available in [Bindplane Growth and Enterprise](https://bindplane.com/pricing).
{% endhint %}

### Quick Start

#### CLI

{% tabs %}
{% tab title="Linux amd64" %}

```bash

# Install the CLI
mkdir -p ~/bindplane
curl -L -o ~/bindplane/bindplane.zip https://storage.googleapis.com/bindplane-op-releases/bindplane/latest/bindplane-ee-linux-amd64.zip
unzip ~/bindplane/bindplane.zip -d ~/bindplane/
sudo mv ~/bindplane/bindplane /usr/local/bin/bindplane
mkdir -p ~/.bindplane/

# Configure with API key
bindplane profile set default --api-key YOUR_API_KEY --remote-url https://app.bindplane.com

# Get started
bindplane get agents
```

{% endtab %}

{% tab title="MacOS amd64" %}

```bash
# Install the CLI
mkdir -p ~/bindplane
curl -L -o ~/bindplane/bindplane.zip https://storage.googleapis.com/bindplane-op-releases/bindplane/latest/bindplane-ee-darwin-amd64.zip
unzip ~/bindplane/bindplane.zip -d ~/bindplane/
sudo mv ~/bindplane/bindplane /usr/local/bin/bindplane
mkdir -p ~/.bindplane/

# Configure with API key
bindplane profile set default --api-key YOUR_API_KEY --remote-url https://app.bindplane.com

# Get started
bindplane get agents
```

{% endtab %}

{% tab title="MacOS arm64" %}

```bash
# Install the CLI
mkdir -p ~/bindplane
curl -L -o ~/bindplane/bindplane.zip https://storage.googleapis.com/bindplane-op-releases/bindplane/latest/bindplane-ee-darwin-arm64.zip
unzip ~/bindplane/bindplane.zip -d ~/bindplane/
sudo mv ~/bindplane/bindplane /usr/local/bin/bindplane
mkdir -p ~/.bindplane/

# Configure with API key
bindplane profile set default --api-key YOUR_API_KEY --remote-url https://app.bindplane.com

# Get started
bindplane get agents
```

{% endtab %}

{% tab title="Windows amd64" %}

```powershell
# Install the CLI
$installPath = "$env:ProgramFiles\bindplane-cli"
if (-not (Test-Path -Path $installPath)) {
    New-Item -Path $installPath -ItemType Directory
    Write-Host "Folder created successfully: $installPath"
} else {
    Write-Host "Folder already exists: $installPath"
}
$currentMachinePath = [System.Environment]::GetEnvironmentVariable("Path", "Machine")
if ($currentMachinePath -notlike "*$installPath*") {
    [System.Environment]::SetEnvironmentVariable("Path", "$currentMachinePath;$installPath", "Machine")
    $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
}
$downloadPath = Join-Path -Path "$env:USERPROFILE\Downloads" -ChildPath bindplane-ee-windows-amd64.zip
Invoke-WebRequest -Uri https://storage.googleapis.com/bindplane-op-releases/bindplane/latest/bindplane-ee-windows-amd64.zip -OutFile $downloadPath
Expand-Archive -Path $downloadPath -DestinationPath $installPath -Force

# Configure with API key
bindplane profile set default --api-key YOUR_API_KEY --remote-url https://app.bindplane.com

# Get started
bindplane get agents
```

{% endtab %}
{% endtabs %}

#### API

```bash
# Make your first API call
curl -H "X-Bindplane-Api-Key: YOUR_API_KEY" https://app.bindplane.com/v1/agents
```

### What's Included

#### CLI (Command Line Interface)

* **Installation**: Cross-platform installation for Linux, macOS, and Windows
* **Commands**: 16+ commands for managing all Bindplane resources
* **Profiles**: Support for multiple environments and configurations
* **Output Formats**: JSON, YAML, table, and raw output options

**Key CLI Commands:**

* `get` - Display resources (collectors, configurations, sources, etc.)
* `apply` - Apply resources
* `delete` - Remove resources
* `install` - Install new collectors
* `rollout` - Manage configuration rollouts
* `profile` - Manage connection profiles

#### REST API

* **Complete Coverage**: All programmatic functionality available via HTTP endpoints
* **RESTful Design**: Standard HTTP methods and status codes
* **JSON Responses**: Consistent JSON format for all responses
* **Rate Limiting**: Built-in rate limiting with exponential backoff support

**API Resource Categories:**

* **Agents**: Manage collector instances and configurations
* **Configurations**: Create and manage telemetry configurations
* **Sources & Destinations**: Configure data sources and outputs
* **Organizations & Users**: Manage access and permissions
* **Rollouts**: Control configuration deployments

### Authentication

Both CLI and API use the same authentication system with [API keys](/cli-and-api/api-keys.md).

#### CLI Configuration

```bash
# Set up a profile with API key
bindplane profile set default --api-key YOUR_API_KEY --remote-url https://app.bindplane.com
bindplane profile use default
```

#### API Headers

```bash
# Include API key in all requests
curl -H "X-Bindplane-Api-Key: YOUR_API_KEY" https://app.bindplane.com/v1/endpoint
```

### Common Use Cases

#### Automation

```bash
# CLI: Automated collector deployment
bindplane install agent --name "web-server-01" --labels "env=prod,role=web"

# API: Programmatic configuration management
curl -X POST -H "X-Bindplane-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-config", "spec": {...}}' \
  https://app.bindplane.com/v1/configurations
```

#### Integration

```bash
# CLI: Export configurations for version control
bindplane get configurations -o yaml > configs.yaml

# API: Integrate with monitoring systems
curl -H "X-Bindplane-Api-Key: $API_KEY" \
  https://app.bindplane.com/v1/agents | jq '.agents[].status'
```

#### Bulk Operations

```bash
# CLI: Bulk agent management
bindplane label agents --add "maintenance=true" --filter "env=staging"

# API: Bulk configuration updates
curl -X PATCH -H "X-Bindplane-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"labels": {"maintenance": "true"}}' \
  https://app.bindplane.com/v1/agents/labels
```

### Error Handling

#### CLI

* Exit codes indicate success/failure
* Detailed error messages with suggestions
* Verbose mode for debugging: `--verbose`

#### API

* Standard HTTP status codes (200, 400, 401, 403, 404, 500)
* JSON error responses with details:

```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```


---

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