Blackbox AI CLI Reference for Hermes Terminal

Delegate coding tasks to Blackbox AI via the Hermes terminal using a multi-model coding agent CLI. This reference covers all capabilities, procedures, parameters, constraints, and failure modes for operating the Blackbox CLI.

When to Use

Use Blackbox CLI when you need to:

• Generate, refactor, or review code using multiple LLMs with automatic best-result selection.
• Perform one-shot code generation or quick scratch work in a temporary directory.
• Run long tasks that benefit from background execution and checkpoint/resume.
• Conduct PR reviews without modifying the working tree.
• Execute independent coding tasks in parallel.

Prerequisites

Before delegating tasks, ensure:

• Node.js 20+ is installed.
• Blackbox CLI is installed globally via npm install -g @blackbox_ai/blackbox-cli (binary: blackbox).
• An API key is obtained from app.blackbox.ai/dashboard.
• The API key is configured via blackbox configure.
• Always use pty=true in all terminal calls.

Parameters and Commands

Core Parameters

• --prompt "task" or -p: Non-interactive one-shot execution with the given task description. Required for one-shot tasks.
• --resume-checkpoint "tag": Resume from a saved checkpoint tag. Optional.
• --yolo or -y: Auto-approve all actions and model switches. Optional.
• --vlm-switch-mode: Image-handling mode. Accepts "once" (switch for current query only), "session" (switch for entire session), or "persist" (stay on current model, no switch). Optional.
• -c, --checkpointing: Enable checkpointing of file edits. Optional.

CLI Management Commands

• blackbox configure: Change settings, providers, and models. Required for initial setup and multi-model configuration.
• blackbox update: Update the CLI to the latest version.
• blackbox mcp: Manage MCP servers.
• blackbox extensions: Manage CLI extensions.
• blackbox voice: Configure voice input.
• blackbox shortcut: Configure the 'b' shortcut.

Session Commands

During interactive sessions, use:

• /compress: Compress the session context.
• /clear: Clear the session.
• /stats: Display session statistics.
• Ctrl+C: Interrupt the current operation.

Token Limit

The sessionTokenLimit parameter controls the token limit for a session, set in .blackboxcli/settings.json (default 32000). Example configuration:

{
  "sessionTokenLimit": 32000
}

Procedures

One-Shot Task Execution

1. Ensure prerequisites are met (Node.js 20+, CLI installed, API key configured, pty=true).
2. Run the task with a prompt and working directory. For example, to add JWT authentication:

terminal(command="blackbox --prompt 'Add JWT authentication with refresh tokens to the Express API'", workdir="/path/to/project", pty=true)

For scratch work in a temporary directory:

terminal(command="cd $(mktemp -d) && git init && blackbox --prompt 'Build a REST API for todos with SQLite'", pty=true)

Background Mode for Long Tasks

1. Start the task in background with PTY:

# Start in background with PTY
terminal(command="blackbox --prompt 'Refactor the auth module to use OAuth 2.0'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Blackbox asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")

2. Capture the returned session_id.
3. Monitor progress using process(action="poll", session_id="<id>") or process(action="log", session_id="<id>").
4. If Blackbox asks a question, send input via process(action="submit", session_id="<id>", data="yes").
5. If needed, kill the session with process(action="kill", session_id="<id>").

Resume from Checkpoint

1. After a task completes, note the checkpoint tag displayed by Blackbox (e.g., task-abc123-2026-03-06).
2. Resume with a follow-up task:

# After a task completes, Blackbox shows a checkpoint tag
# Resume with a follow-up task:
terminal(command="blackbox --resume-checkpoint 'task-abc123-2026-03-06' --prompt 'Now add rate limiting to the endpoints'", workdir="~/project", pty=true)

PR Review (Without Modifying Working Tree)

1. Clone the repository to a temporary directory, checkout the PR, and run Blackbox:

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && blackbox --prompt 'Review this PR against main. Check for bugs, security issues, and code quality.'", pty=true)

Parallel Work

1. Spawn multiple Blackbox instances with background=true for independent tasks:

terminal(command="blackbox --prompt 'Fix the login bug'", workdir="/tmp/issue-1", background=true, pty=true)
terminal(command="blackbox --prompt 'Add unit tests for auth'", workdir="/tmp/issue-2", background=true, pty=true)

# Monitor all
process(action="list")

2. Monitor all sessions using process(action="list").

Capabilities

• Interactive and non-interactive sessions: Run tasks interactively or one-shot.
• Checkpointing and resuming: Save and resume tasks using checkpoint tags.
• Background mode: Run long tasks in background with session monitoring (poll, log, submit, kill).
• Multi-model execution: Runs the same task through multiple models and uses a judge to select the best output.
• Vision support: Automatic detection of images and model switching for multimodal analysis.
• MCP server management: Via blackbox mcp.
• CLI extensions management: Via blackbox extensions.
• Voice input configuration: Via blackbox voice.
• Shortcut configuration: Via blackbox shortcut.
• Token limit control: Via .blackboxcli/settings.json.
• Update CLI: Via blackbox update.
• Configure providers, models, and settings: Via blackbox configure.

Constraints and Caveats

• Always use pty=true — Blackbox CLI is an interactive terminal app and will hang without a PTY.
• Use workdir to keep the agent focused on the correct directory.
• Use background=true for long tasks and monitor with the process tool.
• Do not interfere with running sessions; monitor with poll/log, do not kill because they are slow.
• After completion, check what changed and summarize for the user.
• Blackbox uses a credit-based system; multi-model mode consumes credits faster.
• Verify the blackbox CLI is installed before attempting delegation.
• Multi-model mode: configure multiple providers via blackbox configure to enable Chairman/judge workflow.
• Vision support: Blackbox automatically detects images and can switch to multimodal analysis based on VLM mode.
• Checkpoint tag is displayed after a task completes for use with --resume-checkpoint.

Failure Modes

• Missing PTY (pty=true) causes the CLI to hang.
• Missing or invalid API key prevents authentication.
• Insufficient credits for multi-model or long tasks.
• Node.js version below 20 causes installation or runtime errors.
• CLI not installed: blackbox command not found.
• Session killed prematurely due to impatience (do not kill slow sessions).
• workdir not set leads to agent working in wrong directory.
• Background session not monitored may leave orphan processes.