# Blackbox CLI

> 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.

- Skill: `webrenew/blackbox-cli` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add webrenew/blackbox-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/blackbox-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/blackbox-cli

---


# 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:**
```bash
curl -fsSL https://blackbox.ai/install.sh | bash
```

**Windows (PowerShell):**
```powershell
Invoke-WebRequest -Uri "https://blackbox.ai/install.ps1" -OutFile "install.ps1"; .\install.ps1
```

### Configure

```bash
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](https://app.blackbox.ai/dashboard)
4. Select preferred model

### Start a Session

```bash
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:

```bash
/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**
```bash
# 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**
```bash
blackbox configure
# Enter your API key when prompted
```

**Step 3: Verify**
```bash
blackbox --version
```
If `command not found`, restart your terminal and check your PATH.

**Step 4: Start a session**
```bash
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