Brightpath CLI

Installation

Copy page

Installation

This guide walks you through building Brightpath CLI from source and setting up your environment for optimal usage.

Prerequisites

Before installing Brightpath, ensure you have:

• Go 1.21+: Required for building from source
• Git: For cloning the repository
• API Keys: Provider-specific API keys (see Provider Setup)

Building from Source

Clone the Repository

Code
 
git clone https://github.com/brightforest/brightpath.git
cd brightpath

Build the Binary

Code
 
# Build for your current platform
go build -o brightpath ./cmd/brightpath

# Or use the Makefile
make build

Install Globally

Code
 
# Install to your $GOPATH/bin
go install ./cmd/brightpath

# Or copy the binary to your PATH
sudo cp brightpath /usr/local/bin/

Verify Installation

Code
 
brightpath --version

You should see output similar to:

Code
 
brightpath version 0.1.0

Cross-Platform Builds

Build for different platforms using cross-compilation:

Code
 
# Linux (x86_64)
GOOS=linux GOARCH=amd64 go build -o brightpath-linux ./cmd/brightpath

# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o brightpath-macos-arm64 ./cmd/brightpath

# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o brightpath-macos-amd64 ./cmd/brightpath

# Windows
GOOS=windows GOARCH=amd64 go build -o brightpath.exe ./cmd/brightpath

Environment Setup

Brightpath requires several environment variables depending on which providers you plan to use.

Required Environment Variables

Create a .env file in your project directory or set these in your shell:

Code
 
# Cursor API Configuration
export CURSOR_API_KEY="your-cursor-api-key"
export CURSOR_API_URL="https://api.cursor.sh"  # Optional, defaults to production

# XAI/Grok Configuration (if using XAI models)
export XAI_API_KEY="your-xai-api-key"
export XAI_API_URL="https://api.x.ai/v1"  # Optional

# Linear Configuration (if using Linear provider)
export LINEAR_API_KEY="your-linear-api-key"
export LINEAR_TEAM_ID="your-team-id"  # Optional

# GitHub Copilot Configuration (if using Copilot provider)
export GITHUB_TOKEN="your-github-token"
export COPILOT_API_URL="https://api.github.com"  # Optional

# General Configuration
export BRIGHTPATH_LOG_LEVEL="info"  # debug, info, warn, error
export BRIGHTPATH_CACHE_DIR="$HOME/.brightpath/cache"
export BRIGHTPATH_CONFIG_DIR="$HOME/.brightpath"

Setting Up Environment Variables

On Linux/macOS

Add to your ~/.bashrc, ~/.zshrc, or ~/.profile:

Code
 
# Add to shell configuration file
echo 'export CURSOR_API_KEY="your-cursor-api-key"' >> ~/.bashrc
echo 'export XAI_API_KEY="your-xai-api-key"' >> ~/.bashrc

# Reload your shell configuration
source ~/.bashrc

On Windows (PowerShell)

Code
 
# Set environment variables for current session
$env:CURSOR_API_KEY = "your-cursor-api-key"
$env:XAI_API_KEY = "your-xai-api-key"

# Set permanently
[Environment]::SetEnvironmentVariable("CURSOR_API_KEY", "your-cursor-api-key", "User")
[Environment]::SetEnvironmentVariable("XAI_API_KEY", "your-xai-api-key", "User")

Configuration File

Brightpath uses a YAML configuration file (.brightpath.yaml) to customize behavior and set defaults.

Default Configuration Location

Brightpath looks for configuration in the following order:

1. ./.brightpath.yaml (current directory)
2. $HOME/.brightpath/config.yaml (user home)
3. /etc/brightpath/config.yaml (system-wide)

Configuration File Structure

Create a .brightpath.yaml file in your project or home directory:

Code
 
# .brightpath.yaml

# Default provider to use when none is specified
default_provider: cursor

# Global budget limit (in USD)
budget:
  default_per_task: 5.00
  max_total: 100.00
  warn_threshold: 80.00

# Logging configuration
logging:
  level: info
  format: json  # json or text
  output: stdout  # stdout, stderr, or file path

# Provider-specific configurations
providers:
  cursor:
    api_url: https://api.cursor.sh
    timeout: 300s
    retry_attempts: 3
    model: gpt-4  # default model to use
    
  linear:
    api_url: https://api.linear.app
    timeout: 60s
    default_team: YOUR_TEAM_ID
    
  copilot:
    api_url: https://api.github.com
    timeout: 120s
    
  xai:
    api_url: https://api.x.ai/v1
    timeout: 300s
    model: grok-beta

# Batch operation defaults
batch:
  max_concurrent: 5
  retry_failed: true
  merge_strategy: auto  # auto, manual, or skip
  
# Multi-round orchestration defaults
orchestration:
  max_rounds: 10
  default_split_strategy: parallel
  default_merge_strategy: consensus
  checkpoint_interval: 1  # Save state every N rounds

# Server mode configuration
server:
  host: 0.0.0.0
  port: 8080
  enable_websocket: true
  auth_enabled: true
  rate_limit: 100  # requests per minute

# Cache configuration
cache:
  enabled: true
  ttl: 24h
  directory: ~/.brightpath/cache
  max_size: 1GB

# Output configuration
output:
  format: json  # json, yaml, or text
  pretty: true
  include_metadata: true

Minimal Configuration

For a quick start, you can use a minimal configuration:

Code
 
# .brightpath.yaml (minimal)

default_provider: cursor

providers:
  cursor:
    model: gpt-4
    
budget:
  default_per_task: 5.00

Provider Setup

Different providers require specific configuration. See the Providers documentation for detailed setup instructions for each provider:

• Cursor Provider
• Linear Provider
• Copilot Provider
• PostForMe Provider
• Upload-Post Provider

Verification

After installation and configuration, verify everything is working:

Code
 
# Check version
brightpath --version

# Validate configuration
brightpath config validate

# Test provider connection
brightpath provider test cursor

# List available commands
brightpath --help

Directory Structure

Brightpath creates the following directory structure:

Code
 
$HOME/.brightpath/
├── config.yaml          # User configuration
├── cache/               # Cached data
│   ├── providers/       # Provider-specific cache
│   └── responses/       # API response cache
├── logs/                # Log files
│   ├── brightpath.log
│   └── errors.log
├── state/               # State management
│   ├── batches/         # Batch operation state
│   └── pipelines/       # Pipeline execution state
└── plugins/             # Custom plugins (if any)

Troubleshooting

Binary Not Found After Installation

If brightpath command is not found after installation:

Code
 
# Check if $GOPATH/bin is in your PATH
echo $PATH | grep "$GOPATH/bin"

# If not, add it to your PATH
export PATH="$PATH:$GOPATH/bin"

# Make it permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$PATH:$GOPATH/bin"' >> ~/.bashrc

API Key Issues

If you get authentication errors:

Code
 
# Verify environment variables are set
echo $CURSOR_API_KEY
echo $XAI_API_KEY

# Test provider connectivity
brightpath provider test cursor --verbose

Configuration Not Loading

If Brightpath doesn't seem to use your configuration:

Code
 
# Check which config file is being used
brightpath config path

# Validate configuration syntax
brightpath config validate

# Show loaded configuration
brightpath config show

Permission Denied

If you get permission errors when building or installing:

Code
 
# For building
chmod +x ./build.sh

# For installing globally
sudo cp brightpath /usr/local/bin/
sudo chmod +x /usr/local/bin/brightpath

Updating Brightpath

To update to the latest version:

Code
 
# Pull latest changes
cd /path/to/brightpath
git pull origin main

# Rebuild
make clean
make build

# Reinstall
go install ./cmd/brightpath

Uninstalling

To remove Brightpath from your system:

Code
 
# Remove binary
sudo rm /usr/local/bin/brightpath

# Remove configuration and cache (optional)
rm -rf ~/.brightpath

Next Steps

• Explore available commands
• Create your first batch operation
• Configure providers
• Learn about multi-round orchestration