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

Command	Description
blackbox / blackbox session / blackbox s	Launch interactive chat
blackbox configure	Setup wizard
blackbox project	Open last project directory
blackbox projects	List recent project folders
blackbox run	Execute commands from file
blackbox info	Show system information
blackbox update	Install latest version
blackbox shortcut	Toggle b alias

Slash Commands (In-Session)

Session:

Command	Description
/help	Show available commands
/clear	Clear conversation history
/compress	Compress history to save tokens
/stats	Show session info and token usage
/exit / /quit	Exit session

Agent Management:

Command	Description
/agent	Configure and manage AI agents
/agent configure	Setup dialog for an agent
/agent set <name>	Switch agent (blackbox, claude, codex, gemini, goose, opencode, qwen)
/agent model	Change current agent's model
/agent info	Show current agent config
/agent exit	Exit agent session

Skills:

Command	Description
/skill	Show skill help
/skill list	List all available skills
/skill create <name>	Create a new skill
/skill info <name>	Show skill details

Database:

Command	Description
/db configure	Configure database connection

Multi-Agent:

Command	Description
/multi-agent	Run multiple agents in parallel

Remote Tasks:

Command	Description
/remote <task>	Execute task on remote cloud
/tasks	List and manage remote tasks
/tasks resume <id>	Resume a remote task

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

Issue	Fix
command not found: blackbox	Re-run install script, restart terminal
Execution policy error (Windows)	Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
API key issues	Re-run blackbox configure
Token limit reached	Use /compress to reduce history
Database connection fails	Check connection URI format and network access

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