blackbox-cli

name: blackbox-cli description: > Guides usage of the Blackbox AI CLI terminal agent, including installation, configuration, database chat, multi-agent parallel execution, remote tasks, and skill management. Activates when working with terminal-based Blackbox AI workflows or CLI commands. compatibility: > Requires terminal/shell access. macOS, Linux, or Windows with PowerShell. Node.js 20+ required for source installation. metadata: author: tradecraft version: "1.0.0"

Blackbox AI CLI

The Blackbox AI CLI is a terminal-based AI coding agent that provides interactive chat, database querying, multi-agent execution, remote task management, and skill authoring — all from your terminal.

When to Use This Skill

• Installing or configuring the Blackbox CLI
• Running interactive AI coding sessions in terminal
• Using /db to chat with PostgreSQL, MySQL, MongoDB, or Redis
• Running /multi-agent parallel execution across models
• Managing skills with /skill create, /skill list, /skill info
• Executing remote tasks with /remote
• Configuring agents and models
• Using the blackbox or b shortcut command

Quick Start

Install

Mac/Linux:

curl -fsSL https://blackbox.ai/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri "https://blackbox.ai/install.ps1" -OutFile "install.ps1"; .\install.ps1

Configure

blackbox configure

1. Select "Configure Providers"
2. Choose model provider (Blackbox, Claude, Codex, Gemini, etc.)
3. Enter your API key from app.blackbox.ai/dashboard
4. Select preferred model

Start a Session

blackbox          # Launch interactive session
blackbox s        # Shortcut
b                 # After running `blackbox shortcut`

Core Concepts

Terminal Commands

Slash Commands (In-Session)

Session:

Agent Management:

Skills:

Database:

Multi-Agent:

Remote Tasks:

See references/commands.md for the complete command reference.

Database Chat

Connect to databases and query with natural language:

/db configure

The wizard prompts for database type and connection URI. Then ask questions:

> Show the top 10 products by total revenue last quarter
> List users who signed up in the last 30 days
> Find the top 5 customers by lifetime value

Supported databases: PostgreSQL, MySQL, MongoDB, Redis

See references/database-chat.md for setup and examples.

Multi-Agent Execution

Run the same task across multiple AI agents simultaneously:

/multi-agent

• Dispatches to 2-5 agents (Blackbox, Claude, Codex, Gemini)
• Each agent works on a separate Git branch
• A chairman LLM evaluates and selects the best implementation

See references/multi-agent.md for details.

Remote Tasks

Execute tasks on Blackbox cloud infrastructure:

/remote add authentication feature
/remote fix bug username/other-repo --branch develop

Within a Git repo: Uses current repo and branch automatically. Outside a Git repo: Runs in sandbox mode.

Skills System

Skills live in .blackbox/skills/<name>/SKILL.md and are automatically discovered during sessions:

/skill create api-design    # Creates .blackbox/skills/api-design/SKILL.md
/skill list                 # Lists all skills
/skill info api-design      # Shows skill content

Skills are loaded contextually — Blackbox evaluates task descriptions and activates relevant skills automatically.

Common Patterns

Project Scaffolding

> Create a Next.js app with TypeScript, Tailwind, and shadcn/ui
> Add Supabase authentication with email/password and Google OAuth
> Set up Vitest for unit testing

Debugging

> This function throws "Cannot read property 'map' of undefined" — fix it
> Why is my API route returning 500? Check the error handling

Database Migration

/db configure
> Show me the current schema for the users table
> Add an "avatar_url" column to users and create the migration

Multi-Model Comparison

/multi-agent
> Implement a rate limiter middleware for Express
# Runs on Claude, Codex, and Gemini simultaneously
# Chairman picks the best implementation

Workflows

First-Time Setup

Copy this checklist and track your progress:

CLI Setup Progress:
- [ ] Step 1: Install the CLI
- [ ] Step 2: Configure API key
- [ ] Step 3: Verify installation
- [ ] Step 4: Start first session
- [ ] Step 5: Try a test task

Step 1: Install

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/user/blackbox-cli/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/user/blackbox-cli/main/install.ps1 | iex

Step 2: Configure

blackbox configure
# Enter your API key when prompted

Step 3: Verify

blackbox --version

If command not found, restart your terminal and check your PATH.

Step 4: Start a session

blackbox

Step 5: Test

> Explain what this project does based on the README

Database Chat Setup

Database Chat Progress:
- [ ] Step 1: Configure connection URI
- [ ] Step 2: Verify connection
- [ ] Step 3: Inspect schema
- [ ] Step 4: Run first query

Step 1: Run /db configure and enter your connection URI (e.g., postgresql://user:pass@host:5432/db).

Step 2: Run /db status to verify connectivity. If it fails, check URI format and network access.

Step 3: Ask the agent to show tables: Show me all tables in this database.

Step 4: Run a read-only query: How many users signed up this month?. Database chat runs read-only operations only.

Multi-Agent Execution

Multi-Agent Progress:
- [ ] Step 1: Launch multi-agent mode
- [ ] Step 2: Define the task
- [ ] Step 3: Monitor agent progress
- [ ] Step 4: Review evaluations
- [ ] Step 5: Select winning implementation

Step 1: Run /multi-agent to start parallel execution mode.

Step 2: Describe the task. Each agent (Claude, Blackbox, Codex, Gemini) works on it independently in separate git branches.

Step 3: Monitor progress — each agent runs in its own worktree.

Step 4: The Chairman LLM evaluates all implementations on correctness, code quality, completeness, and efficiency.

Step 5: Review the ranked results and accept the best implementation. The winning branch is merged into your working branch.

Troubleshooting

References

• See references/commands.md for complete command reference
• See references/database-chat.md for database connection and querying
• See references/multi-agent.md for multi-agent workflows