Skip to main content
The Buster CLI is used to authenticate, deploy agents, and manage your Buster configuration.

​
Installation

  • macOS / Linux
  • Windows
  • GitHub Actions
curl -fsSL https://install.buster.so | sh

​
Installation Locations

PlatformLocation
macOS/Linux~/.local/bin/buster
Windows%LOCALAPPDATA%\Microsoft\WindowsApps\buster.exe
The CLI is a standalone binary with no runtime dependencies—no Node.js or other runtimes required.

​
Verify Installation

buster --version

​
Commands

​
buster

Launch the interactive terminal UI for conversational interaction with the AI agent. 
buster
This opens a TUI (terminal user interface) where you can chat with Buster interactively.

​
buster auth

Authenticate with the Buster API. 
# Interactive authentication
buster auth

# Direct authentication with API key
buster auth --api-key YOUR_API_KEY

# Show current credentials
buster auth --show

# Clear saved credentials
buster auth --clear

​
Options

OptionDescription
--api-key <key>Your Buster API key
--host <url>Custom API host URL
--localUse local development server (http://localhost:3001)
--cloudUse cloud instance (https://api2.buster.so)
--showDisplay current credentials
--clearClear saved credentials
--no-saveDon’t save credentials to disk (one-time use)

​
Credentials File

Credentials are saved to ~/.buster/credentials.json.
For CI/CD pipelines, use the BUSTER_API_KEY environment variable instead of saving credentials to disk.

​
buster deploy

Deploy semantic models and agents to the Buster platform. 
# Deploy from current directory
buster deploy

# Deploy from specific path
buster deploy --path ./my-project

# Validate without deploying
buster deploy --dry-run

# Show detailed output
buster deploy --verbose

​
Options

OptionDescription
--path <path>Path to search for buster.yml (defaults to current directory)
--dry-runValidate configuration without deploying
--verboseShow detailed output
--debugEnable debug mode with detailed logging
--skip-automationSkip agent deployment (deploy models only)
--skip-modelsSkip model deployment (deploy agents only)

​
What Gets Deployed

  1. Projects — Data model definitions from buster.yml
  2. Agents — Custom agents from the agents field
  3. Monitors — Data quality monitors from the monitors field
  4. Logs configuration — Query logs writeback settings

​
buster init

Initialize a new Buster project with configuration files. 
# Interactive setup in current directory
buster init

# Initialize in specific directory
buster init --path ./new-project

# Pre-provide API key
buster init --api-key YOUR_API_KEY

​
Options

OptionDescription
--path <path>Project location (defaults to current directory)
--api-key <key>Your Buster API key
--host <url>Custom API host URL
--localUse local development server

​
What Gets Created

  • buster.yml — Main configuration file
  • buster/ directory — Project structure
  • Example models and documentation

​
buster settings

Manage CLI settings. 
# Show current settings
buster settings --show

# Enable vim keybindings
buster settings --vim-mode true

# Disable vim keybindings
buster settings --vim-mode false

# Toggle a setting
buster settings --toggle vim-mode

​
Options

OptionDescription
--showShow current settings
--vim-mode <enabled>Enable or disable vim keybindings (true/false)
--toggle <setting>Toggle a specific setting

​
Settings File

Settings are saved to ~/.buster/settings.json.

​
buster update

Update the Buster CLI to the latest version. 
# Update to latest version
buster update

# Check for updates without installing
buster update --check

# Force update even if on latest
buster update --force

# Skip confirmation prompt
buster update --yes

​
Options

OptionDescription
--checkCheck for updates without installing
--forceForce update even if on latest version
--yesSkip confirmation prompt
The CLI automatically checks for updates in the background and shows a notification when a new version is available.

​
Global Options

These options work with any command:
OptionDescription
--cwd <path>Set working directory for the CLI
--debugEnable debug logging to ~/.buster/logs/debug.log

​
Headless Mode Options

For running agents programmatically (used internally by the platform):
OptionDescription
--prompt <prompt>Run agent in headless mode with the given prompt
--researchRun agent in research mode (read-only, no file modifications)
--contextFilePath <path>Path to context file to include as system message
--chatId <id>Continue an existing conversation
--messageId <id>Message ID for tracking
--includeTools <tools>Comma-separated list of additional tools (e.g., slack_tool)

​
Environment Variables

​
User Configuration

VariableDescriptionDefault
BUSTER_API_KEYAPI key for authentication—
BUSTER_HOSTAPI host URLhttps://api2.buster.so
BUSTER_API_URLAlternative to BUSTER_HOST—

​
Priority Order

  1. Environment variables (highest priority)
  2. Command-line flags
  3. Saved credentials file (lowest priority)

​
Common Workflows

​
First-Time Setup

# 1. Install the CLI
curl -fsSL https://install.buster.so | sh

# 2. Authenticate
buster auth --api-key YOUR_API_KEY

# 3. Initialize a project (optional)
buster init

# 4. Deploy
buster deploy

​
CI/CD Deployment

# GitHub Actions example
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: buster-so/buster/actions/install@v1
        with:
          version: latest
      
      - run: buster deploy
        env:
          BUSTER_API_KEY: ${{ secrets.BUSTER_API_KEY }}

​
Validating Before Deploy

# Check for errors without deploying
buster deploy --dry-run --verbose

​
Debugging Issues

# Enable debug logging
buster deploy --debug

# View debug logs
cat ~/.buster/logs/debug.log

​
Troubleshooting

​
”No buster.yml found”

Ensure buster.yml exists in your repository root or specify a path: 
buster deploy --path ./my-project

​
“No API key found”

Run buster auth to configure credentials: 
buster auth --api-key YOUR_API_KEY
Or set the environment variable: 
export BUSTER_API_KEY="your-key"

​
“Invalid agent configuration”

Validate your configuration: 
buster deploy --dry-run --verbose
Check for:
  • Valid YAML syntax
  • Required fields: name, prompt, triggers
  • Valid trigger event types

​
Debug Logging

Enable detailed logging to troubleshoot issues: 
buster --debug deploy
Logs are written to ~/.buster/logs/debug.log.