CLI Reference

Version: 3.1 | Last updated: 2026-07-22

The bluebox CLI lets you set up Bluebox and ask questions from your terminal.

If you want your coding agent to install it for you, paste this prompt into the agent:

Install Bluebox CLI from https://app.bluebox.ai without piping a remote script into a shell. Download the installer for your platform — https://app.bluebox.ai/install.sh for macOS/Linux, https://app.bluebox.ai/install.ps1 for Windows PowerShell, or https://app.bluebox.ai/install.cmd for Windows Command Prompt — to a local file, show me what it will do, then run it to start Bluebox setup.

If you prefer to run setup yourself, use the installer for your platform:

macOS and Linux:

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

Windows — PowerShell:

irm https://app.bluebox.ai/install.ps1 | iex

Windows — Command Prompt:

curl -fsSL https://app.bluebox.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Run the same command at any time to update the CLI to the latest version.

Common commands

bluebox version

Print the installed CLI version.

bluebox version

Prints a semantic version such as 1.2.3.

bluebox setup

Run or re-run the Bluebox onboarding flow. Handles authentication, installs coding-agent skills, and opens the Setup page in your browser to connect your repository and retrieve your ingest token. Observability instrumentation is completed locally by your coding agent.

bluebox setup

Supported coding agents for automatic skill installation:

Agent	Support level
Claude Code	✓ Fully supported
Kiro	✓ Fully supported
GitHub Copilot	⚠ Experimental
Cursor	⚠ Experimental
OpenCode	⚠ Experimental

You can install skills into other coding agents manually — see Installing skills into other agents below.

Kiro: Skills are loaded on demand, not at session start. See Connections — Kiro IDE for how to add a steering file so Kiro has Bluebox context in every session.

Installing skills into other agents

If you use a coding agent that is not yet supported by bluebox setup, install Bluebox skills directly into a directory using bluebox skills install:

bluebox skills install

With no arguments, this writes every skill into .agents/skills/ in your current directory — a fallback layout many editors and custom integrations can read. Pass a directory to install somewhere else:

bluebox skills install ~/shared-skills

If your agent uses one of the conventions bluebox setup already knows — Claude Code, Cursor, Windsurf, GitHub Copilot, Kiro, Codex, or OpenCode — pass its flag instead of the generic layout, and combine flags to write more than one convention at once. Add --generic to also write the fallback layout alongside it:

bluebox skills install --claude --cursor

bluebox skills install --claude --generic

To see every skill before installing, list them first:

bluebox skills list

Files written by bluebox skills install are kept up to date by bluebox skills refresh (below), the same as skills bluebox setup installs automatically.

bluebox skills refresh

Update your installed Bluebox coding-agent skills to the latest versions.

bluebox skills refresh

Bluebox occasionally ships updated skills. Run bluebox skills refresh any time, to keep your Bluebox skills up to date.

Flag	Description
--force	Overwrite skill files you have edited locally. Without --force, locally-edited skill files are preserved and listed on stderr with a message suggesting --force.

Exit codes: 0 on success. 1 on authentication or network error.

bluebox auth login

Authenticate with Bluebox using the device authorization flow. bluebox setup already handles authentication for you, so you normally only need this command if you manually logged out or your token expired.

bluebox auth login

The CLI prints a verification URL and an eight-character code. Open the URL in any browser, enter the code, and approve. The token is stored securely in your OS keyring (macOS Keychain, Linux Secret Service), with an access-restricted file as fallback.

Flag	Description
--no-browser	Print the URL without opening it automatically
--no-keyring	Force file-based token storage
--device-label <label>	Override the auto-derived device label (default: hostname-os)

Sign-in tokens expire after 14 days of inactivity; run bluebox auth login again to re-authenticate.

bluebox auth logout

Clear stored credentials.

bluebox auth logout

After logout, run bluebox auth login to authenticate again.

bluebox ask

Query Bluebox from the terminal. The agent streams its answer to stdout; progress goes to stderr. Use it for live questions about your services, and for questions about Bluebox itself — concepts, setup, and how it handles your data.

bluebox ask [flags] "<question>"

Flag	Description
--service <name>	Service name for the agent to use as context
--env <name>	Deployment environment (e.g. production, staging)
--since <window>	Time window for the question, as a relative duration (e.g. 7d, 24h, 30m). Defaults to the last 24h when omitted.
--repo-url <url>	Repository URL. Auto-detected from the git origin remote when you run ask inside a repository; pass this to override it or to supply one when detection finds nothing.
--entity-id <id>	Monitored entity ID (e.g. SERVICE-...) for an exact service match
--conversation-id <uuid>	Continue an existing conversation
--continue	Continue the most recent ask conversation without copying its ID. --conversation-id takes precedence if both are given.
--workspace <id>	Target this workspace for this call only, without changing your saved workspace

When you run ask inside a git repository, the CLI detects the repository from its origin remote and sends it as context, so the agent can tie your question to the right service. Use --repo-url to override the detected value.

ask needs your workspace connected to your observability environment. If it isn't, the command reports that and points you to bluebox setup instead of answering without data.

If your workspace has used all of its AI usage, ask tells you so, shows when your usage resets, and points you to bluebox usage for the details — it does not run the question.

Exit codes: 0 on success, non-zero on failure, timeout, or cancellation. On non-zero exit, check stderr for the error.

At the end of each run, the conversation ID is printed. Pass it with --conversation-id to continue the thread.

Examples:

# Ask a one-off question with service context
bluebox ask --service checkout --env production "any error rate spikes in the last 30 minutes?"

# Ask without narrowing scope
bluebox ask "what are the top failing services right now?"

# Set the time window (defaults to the last 24h when omitted)
bluebox ask --service checkout --since 7d "any error rate spikes?"

# Override the auto-detected repository (e.g. when the origin remote is wrong)
bluebox ask --repo-url https://github.com/acme/checkout "why is checkout slow?"

# Pin the exact service by its monitored entity ID
bluebox ask --entity-id SERVICE-1A2B3C4D5E6F7890 "why is checkout slow?"

# Ask about Bluebox itself
bluebox ask "how does Bluebox handle my data and privacy?"

# Continue a conversation
bluebox ask --conversation-id <uuid> "and what about the database layer?"

# Continue the most recent conversation (no UUID needed)
bluebox ask --continue "and what about the database layer?"

# Pipe the answer
bluebox ask --service payments "list the top 5 error messages in the last hour" | jq -R .

bluebox otlp-endpoint

Print the OTLP ingest endpoint for your workspace to stdout — just the URL, nothing else.

bluebox otlp-endpoint

This is the endpoint your services send telemetry to. The Bluebox instrumentation skill runs this command automatically to fill in the .env.otel.bluebox-template file your coding agent completes; you can also run it yourself if you're wiring things up by hand.

The command either prints the endpoint, tells you Bluebox is still preparing it, or explains that a workspace owner needs to finish monitoring-environment setup in the Bluebox web frontend before retrying.

The command never prints your ingest token. Copy the token from the Setup page in your browser instead — Bluebox keeps it out of the CLI so it can't be captured by a coding agent or committed to your repository.

bluebox workspace list

List the workspaces you belong to and see which one the CLI is currently using.

bluebox workspace list

The active workspace is marked in the output. If you have not switched workspaces before, Bluebox shows your primary workspace as active.

Flag	Description
--json	Print the list as JSON instead of a table

bluebox workspace switch

Change which workspace the CLI uses for ask and otlp-endpoint.

bluebox workspace switch

Run it with no arguments in an interactive terminal to see a numbered list and choose one. In a script or CI, pass the workspace ID directly:

bluebox workspace switch <id>

Bluebox checks that you belong to the workspace before switching, so a mistyped or inaccessible ID is rejected before anything is saved.

The --workspace flag

Some commands accept --workspace <id> to target a specific workspace for a single call, without changing your saved workspace. This is useful for scripts that need to reach more than one of your workspaces.

bluebox ask --workspace <id> "any error rate spikes in the last 30 minutes?"
bluebox otlp-endpoint --workspace <id>

If your saved workspace becomes inaccessible — for example, if you're removed from it — the affected commands tell you and point you to bluebox workspace list and bluebox workspace switch to pick another one.

Environment variables

Variable	Description
BLUEBOX_TOKEN	Token for the current invocation only — never stored. Use for scripting and CI.
BLUEBOX_API_URL	Override the Bluebox API URL for the current invocation.
BLUEBOX_DISABLE_KEYRING	Set to 1 to force file-based credential storage. Useful on headless servers without a running keyring service.

Installation details

The installer supports macOS, Linux, and Windows natively (experimental) or via WSL2.

macOS and Linux: the binary is placed at ~/.bluebox/bin/bluebox. If ~/.local/bin is already in your PATH, the installer creates a symlink there so the command is available immediately. Otherwise, it appends ~/.bluebox/bin to your shell startup file (.bashrc, .zshrc, or .profile).

Windows: the binary is placed at %USERPROFILE%\.bluebox\bin\bluebox.exe. The installer adds that directory to your user PATH permanently so the command is available in new terminals.

If the command is not found after install, open a new terminal or add the install directory to your path for the current session:

macOS/Linux:

export PATH="$HOME/.bluebox/bin:$PATH"

Windows PowerShell:

$env:PATH = "$env:USERPROFILE\.bluebox\bin;" + $env:PATH