Skip to main content
Complete reference for all BLACKBOX CLI commands and keyboard shortcuts.

​
Core Commands

CommandDescription
blackbox configureConfigure Blackbox settings
blackbox infoDisplay Blackbox information
blackbox mcpRun one of the mcp servers bundled with blackbox
blackbox sessionStart or resume interactive chat sessions [aliases: s]
blackbox projectOpen the last project directory [aliases: p]
blackbox projectsList recent project directories [aliases: ps]
blackbox runExecute commands from an instruction file or stdin
blackbox recipeRecipe utilities for validation and deeplinking
blackbox scheduleManage scheduled jobs [aliases: sched]
blackbox updateUpdate the blackbox CLI version
blackbox benchEvaluate system configuration across a range of practical tasks
blackbox webExperimental: Start a web server with a chat interface
blackbox helpPrint this message or the help of the given subcommand(s)

​
In-Session Commands

These commands are available within an active BLACKBOX CLI session (after running blackbox or blackbox session):
CommandDescription
/agentConfigure, switch, and manage AI agents
/multi-agentRun multiple AI agents in parallel on separate branches
/skillManage skills to extend AI agent capabilities with specialized knowledge
/tasksList and manage your remote cloud tasks

​
Installation Commands

Platform-specific installation commands:
Unix/Linux/macOS
curl -fsSL https://blackbox.ai/install.sh | bash
Windows (PowerShell)
Invoke-WebRequest -Uri "https://blackbox.ai/install.ps1" -OutFile "install.ps1"; .\install.ps1

​
Configuration Commands

Set up and manage your BLACKBOX CLI configuration: 
# Initial configuration
blackbox configure

​
Multi-Agent Execution

The /multi-agent command enables parallel execution of multiple AI agents on the same task, with each agent working on a separate Git branch. This powerful feature allows you to compare different AI approaches and select the best implementation.
How It Works
When you use /multi-agent, BLACKBOX CLI:
  1. Creates Separate Branches: Automatically creates a unique Git branch for each AI agent
  2. Parallel Execution: Runs multiple agents simultaneously on the same task
  3. Independent Work: Each agent works independently on its own branch
  4. Comparison: Allows you to review and compare different implementations
Default Agents
By default, /multi-agent uses your BLACKBOX API key to invoke:
  • Claude (Anthropic’s Claude models)
  • Blackbox (BLACKBOX AI models)
OpenAI Integration
If you have an OpenAI API key configured, the command will also invoke:
  • Codex (OpenAI’s GPT-5.2 Codex)
  • Gemini (GEMINI’s Gemini-3-pro)
This gives you up to three different AI implementations to compare.
Usage
# Start a BLACKBOX CLI session
blackbox

# Use multi-agent for your task
> /multi-agent create a REST API with user authentication and CRUD operations
Configuration
To enable Codex (OpenAI) or Gemini (Gemini API KEY) in multi-agent mode:
  1. Add your OpenAI API key or Gemini API Key to your environment
  2. The /multi-agent command will automatically include Codex in future executions
Benefits
  • Quality Comparison: Compare implementations from different AI models
  • Best Practices: See different approaches to the same problem
  • Error Reduction: Multiple implementations help identify potential issues
  • Learning: Understand different coding patterns and techniques
  • Flexibility: Choose the implementation that best fits your needs
Example Workflow
# Start session
blackbox session

# Run multi-agent task
> /multi-agent build a todo app with React and TypeScript

# BLACKBOX CLI will:
# 1. Create branch: multi-agent-claude-<timestamp>
# 2. Create branch: multi-agent-blackbox-<timestamp>
# 3. Create branch: multi-agent-codex-<timestamp> (if OpenAI key configured)
# 4. Create branch: multi-agent-gemini-<timestamp> (if Gemini key configured)
# 5. Each agent works independently on its branch
# 6. Review the branches to compare implementations
Best Practices
  • Complex Tasks: Use /multi-agent for complex features where multiple approaches could be valuable
  • Critical Code: Ideal for security-sensitive or performance-critical implementations
  • Learning: Great for understanding different AI coding styles and patterns
  • Branch Management: Review and merge the best implementation, then clean up unused branches
The /multi-agent command requires an active Git repository. Ensure you’re in a Git-initialized project directory before using this feature.

​
Remote Task Management

The /tasks command enables you to list and manage your remote cloud tasks directly from the BLACKBOX CLI. This powerful feature allows you to monitor, resume, and interact with tasks running on the Blackbox Cloud platform.
Available Commands
CommandDescription
/tasksList all your remote cloud tasks
/tasks resume <task-id>Resume a specific remote task by its ID
/chat resume <chat-id>Resume a cloud chat session by its ID
How It Works
When you use /tasks, BLACKBOX CLI:
  1. Fetches Remote Tasks: Connects to Blackbox Cloud and retrieves your task list
  2. Displays Task Status: Shows task IDs, status, and relevant details
  3. Enables Resumption: Allows you to continue working on any task from your terminal
Usage
# Start a BLACKBOX CLI session
blackbox

# List all your remote tasks
> /tasks

# Resume a specific task
> /tasks resume task_abc123

# Resume a chat session
> /chat resume chat_xyz789
Benefits
  • Seamless Cloud Integration: Manage remote tasks without leaving your terminal
  • Task Continuity: Resume interrupted tasks exactly where you left off
  • Unified Workflow: Bridge local CLI and cloud-based agent execution
  • Real-time Monitoring: View task status and progress from the command line
Example Workflow
# Start session
blackbox session

# Check your remote tasks
> /tasks

# Output shows:
# ID              | Status    | Created
# task_abc123     | running   | 2 hours ago
# task_def456     | completed | 1 day ago
# task_ghi789     | paused    | 3 days ago

# Resume a paused task
> /tasks resume task_ghi789

# The CLI connects to the remote task and continues execution
Best Practices
  • Regular Monitoring: Use /tasks to keep track of long-running remote tasks
  • Task Organization: Note task IDs for important work you may need to resume
  • Cloud Sync: Ensure you’re logged in to Blackbox Cloud for full functionality
The /tasks command requires an active Blackbox Cloud account. Make sure you’re authenticated with your Blackbox API key to access your remote tasks.

​
Agent Management

The /agent command allows you to configure, switch between, and manage different AI agents within the BLACKBOX CLI. This powerful feature enables you to leverage multiple AI providers while preserving conversation context.
Available Commands
CommandDescription
/agent configureOpen dialog to configure an agent
/agent set <agent-name>Quickly switch to a different configured agent
/agent modelChange the model for the current agent
/agent infoDisplay current agent configuration
/agent exitExit the current agent session
Quick Agent Switching
The /agent set command allows instant switching between configured agents: 

# Switch back to Blackbox
/agent set blackbox

# Switch to Claude agent
/agent set claude

# Switch to Codex agent
/agent set codex

# Switch to Gemini agent
/agent set gemini

# Switch to Goose agent
/agent set goose

# Switch to OpenCode agent
/agent set opencode

# Switch to Qwen agent
/agent set qwen
Features:
  • Tab Completion: Autocomplete filters agents based on partial input and API key availability
  • Per-agent Model Persistence: Each agent remembers its configured model, so switching back restores your preferred model
Context Preservation
A key feature of the agent management system is conversation history preservation:
  • Context on Agent Switch: When switching between agents, the full conversation history is synced to the new agent
  • Model Change Without Context Loss: Changing models via /agent model no longer clears conversation history
  • Seamless Multi-turn Conversations: CLI agents (Claude, Codex, Gemini) receive the full conversation context when switching from Blackbox
Supported Agents
BLACKBOX CLI supports multiple AI agents, all accessible with a single BLACKBOX API key:
  • Blackbox: BLACKBOX AI’s native models
  • Claude: Anthropic’s Claude models
  • Codex: OpenAI’s specialized programming models
  • Gemini: Google’s multimodal models
  • Goose: Full access to all Blackbox CLI models
  • OpenCode: Complete model support with BLACKBOX API key
  • Qwen: All Blackbox CLI models available
All agents can be configured via /agent configure and switched instantly with /agent set <agent-name>.
Usage Examples
# Start a conversation with the default agent
blackbox session

# Configure a different agent
/agent configure
# [Dialog opens for configuration - select from Blackbox, Claude, Codex, Gemini, Goose, OpenCode, or Qwen]

# Switch to a different agent mid-conversation
/agent set claude
# [Conversation continues with Claude agent, preserving context]

# Switch to one of the new agents
/agent set goose
/agent set opencode
/agent set qwen

# Change the model for the current agent
/agent model
# [Dialog opens to select a different model]

# Check current agent configuration
/agent info
# [Displays current agent and model information]

# Exit the agent session
/agent exit
Benefits
  • Flexibility: Easily switch between different AI providers based on task requirements
  • Continuity: Maintain conversation flow when changing agents or models
  • Efficiency: No need to repeat context or instructions when switching agents
  • Comparison: Test how different agents handle the same conversation thread
Agent switching preserves context, allowing you to seamlessly continue conversations across different AI providers without losing history or having to repeat information.

​
Keyboard Shortcuts

General Controls
ShortcutDescriptionContext
Ctrl+CCancel current input or generationStandard interrupt / Exit BLACKBOX CLI session
Ctrl+DExit BLACKBOX CLI sessionEOF signal
Ctrl+LClear terminal screenKeeps conversation history
Up/Down arrowsNavigate command historyRecall previous inputs
Multiline Input
MethodShortcutContext
Quick escape\ + EnterWorks in all terminals
macOS defaultOption+EnterDefault on macOS
Control sequenceCtrl+JLine feed character for multiline
Paste modePaste directlyFor code blocks, logs