CLI — BlueForge Developer Docs

Installation

Install the CLI globally via npm. Requires Node.js 18+.

npm install -g blueforge-cli

Verify installation:

bash

$ blueforge --version
blueforge-cli v1.0.0

$ blueforge --help
Usage: blueforge [options] [prompt]

Options:
  --version, -v      Show version
  --help, -h         Show help
  --model, -m        LLM model to use
  --provider, -p     LLM provider (anthropic, gemini, openai)
  --serve            Start HTTP API server
  --port             HTTP server port (default: 3202)
  --api-key          API key for HTTP auth

Three Modes

BlueForge CLI runs in three distinct modes depending on your workflow.

One-shot

Pass a prompt as an argument. The agent executes it and exits. Perfect for CI/CD and scripts.

Default

Interactive

Rich TUI with real-time streaming, tool approval, and conversation history. Full REPL experience.

TUI

HTTP Server

REST API + SSE streaming + web dashboard. Control the agent remotely from any client.

API

One-shot Mode

Execute a single prompt and exit. Ideal for automation and scripting.

bash

# Simple code generation
blueforge "Add a login page with email and password fields"

# Specify model
blueforge -m claude-sonnet-4-20250514 "Refactor auth.ts to use JWT"

# Use in CI/CD pipeline
blueforge -p gemini "Generate unit tests for src/utils/"

Interactive Mode

Start without a prompt to enter the interactive TUI. Supports conversation history, tool approval, and rich formatting.

bash

# Start interactive session
blueforge

# With a specific provider
blueforge -p anthropic

# Inside the TUI:
> Build a todo app with Supabase auth
  Agent is thinking...
  Tool: file_write (src/app/page.tsx)
  [a]pprove / [d]eny / [e]dit? a
  ...

Type /help inside the TUI to see available commands. /clear resets conversation history. /exit quits.

HTTP Server Mode

Start the CLI as a REST API server. Includes a built-in web dashboard for real-time monitoring.

bash

# Start server on default port (3202)
blueforge --serve

# Custom port with API key auth
blueforge --serve --port 8080 --api-key my-secret-key

# Dashboard available at:
http://localhost:3202/

API Endpoints

Method	Path	Description
GET	`/health`	Health check and registered tools count
POST	`/api/agent/run`	Execute a prompt (SSE streaming response)
POST	`/api/agent/approve`	Approve a pending tool call
GET	`/api/project/files`	List project files
GET	`/api/project/file?path=`	Read a specific file
GET	`/api/screenshot`	Capture browser screenshot (headless)

SSE Streaming Example

bash

# Stream agent response via curl
curl -N -X POST http://localhost:3202/api/agent/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-key" \
  -d '{"prompt": "Add dark mode toggle"}'

Docker

Run BlueForge CLI in a container. The Docker image includes Playwright for headless browser operations.

Dockerfile

# One-shot mode
docker run --rm \
  -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=sk-... \
  blueforge-cli "Build a landing page"

# HTTP server mode
docker run -d \
  -p 3202:3202 \
  -v $(pwd):/workspace \
  -e BLUEFORGE_API_KEY=my-key \
  -e ANTHROPIC_API_KEY=sk-... \
  blueforge-cli --serve

# Build from source
docker build -t blueforge-cli .

Volume mount: Always mount your project directory as /workspace to give the agent access to your codebase.

Configuration

Environment Variables

ANTHROPIC_API_KEY Claude models (Sonnet, Opus, Haiku)

GEMINI_API_KEY Google Gemini models

OPENAI_API_KEY GPT-4o, o1, o3 models

BLUEFORGE_API_KEY HTTP server authentication

Priority Order (BYOK)

API keys are resolved in this order:

Priority

1. CLI arguments      (--provider, --model)
2. Environment vars    (ANTHROPIC_API_KEY, etc.)
3. Local config       (~/.blueforge/config.json)
4. Admin settings     (Team/org global config)

Local Config File

~/.blueforge/config.json

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "apiKeys": {
    "anthropic": "sk-ant-...",
    "gemini": "AIza..."
  }
}