CLI Reference
Version: 5.1 | Last updated: 2026-09-17
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
To update later, run bluebox update, or re-run the installer command above at any time. Both 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. Add --output json for a machine-readable {"version": …, "build": …} object.
Most commands that print machine-readable output accept --output json. The older --json flag still works on the commands that had it but is deprecated — it prints a one-time notice and you should move to --output json.
bluebox update
Check for a newer bluebox CLI release and install it.
bluebox update
If you installed the CLI with the standalone installer above (the default), this downloads the new version, verifies its checksum, and replaces the running binary. You don't need to re-run the installer. If you're already on the latest version, it prints a confirmation and exits without downloading anything.
If Bluebox detects the CLI was installed a different way (for example, a package manager), it prints how to update through that channel instead of touching the binary. If it can't determine how the CLI was installed, it prints the same installer commands from the top of this page.
Pass --force to reinstall even if you're already on the latest version, which helps if your binary is behaving oddly but still reports the current version. --force only has an effect on the standalone install channel; on any other channel there's nothing to reinstall, so it's a no-op.
Exit codes: 0 on success, including "already up to date" and the hand-off/manual cases. 1 on failure (for example a network or checksum error); your existing binary is always left untouched when the exit code is non-zero.
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
If you're already signed in, the sign-in step also offers a Sign out button behind a confirmation, so you can hand this machine to a different GitHub account without restarting setup elsewhere.
If you belong to more than one Bluebox workspace, authentication is followed by a prompt asking which workspace this machine should use; with only one workspace, Bluebox selects it automatically. Re-run bluebox setup at any time to change your workspace. It shows the same prompt, pre-selecting your current one. See bluebox workspace switch for a non-interactive way to do the same thing.
Setup runs in an interactive terminal window of at least 80x20. In a smaller window it shows your current size alongside the required one and waits while you resize. When there is no terminal to draw in (say you pipe the output or run it from a script), it stops and tells you. In either case you can ask your coding agent to run bluebox setup for you instead.
The review screen at the end of bluebox setup shows your observability-connection status (connected, with its endpoint, or not yet connected) alongside the other setup sections.
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
Each skill gets one row: name, version, and description. Descriptions can be long, so they are shortened to fit your terminal and end with …. To read them in full, wrap them across several lines instead:
bluebox skills list --wide
Shortening only happens when Bluebox is writing to your terminal. If you pipe or redirect the output, you get the whole description on one line, so searching it works:
bluebox skills list | grep -i opentelemetry
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 auth status
Check whether you are signed in, and to which host and workspace — without making a network call.
bluebox auth status
It reports your login state, the host, the token's expiry, where the token is stored, the device label, and the pinned workspace. It exits 0 when you are signed in and non-zero when you are not, so you can use it as a quick check in a script. Add --output json for a machine-readable object (printed whether or not you are signed in). Your secret token is never printed.
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 |
--task-id <id> | Answer from a past investigation's stored context instead of querying fresh. Give its id: a UUID or the base62 task_… form. |
--conversation-id <uuid> | Continue an existing conversation |
--continue | Continue the most recent ask conversation for your current workspace, without copying its ID. Each workspace keeps its own most recent conversation, so switching workspaces and back resumes that workspace's own thread. --conversation-id takes precedence if both are given. |
--workspace <id> | Target this workspace for this call only, without changing your saved workspace |
Write flags with two dashes, like --service. A single-dash spelling such as -service is not recognized. Put flags before the question: a flag written after the question is treated as part of the question text itself, and ask warns you when it spots one there.
ask needs an actual question. Running it with nothing, or with an empty or blank one (ask ""), is refused the same way, so you don't spend a turn on a question you never meant to ask.
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.
Asking from a repository with multiple services
If your repository holds more than one deployed service (for example, separate services living in services/payments/ and services/checkout/), ask automatically sends your current working directory and which parts of the repository you changed (never file contents) as extra context. It sends the modules your changes touch (the directories that hold a project manifest such as go.mod, package.json, or a Dockerfile) rather than a long list of individual files, so the signal stays small and meaningful. This lets the agent scope its answer to the specific service or services your work touches, instead of treating the whole repository as one service.
When a question touches more than one service, ask includes context from each affected service in its answer. If part of your working directory or changed files doesn't match any known service, ask says so directly rather than silently guessing or falling back to the whole repository. Pass --service or --entity-id to be explicit about which service you mean.
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 and shows when your usage resets. It does not run the question. Your workspace's usage figures are on the Usage page in Bluebox, under Settings.
Reading the Evidence section
Every ask answer includes an Evidence section in the answer itself: what was queried to answer, the numbers that back the conclusion, and where coverage fell short. Gaps are named plainly: data that came back empty, a query that failed, or a query Bluebox declined to run (an unverified service mapping, a time window over the workspace cap, a security rule). When something failed and there is a useful next step, the answer says so rather than leaving a bare error.
Exit codes: 0 on success, non-zero on failure, timeout, or cancellation. On non-zero exit, check stderr for the error. A flag ask does not recognize is a usage error: it prints the flag and the command's help to standard error and exits with 1.
At the end of each run, the conversation ID is printed to standard error, alongside the progress output. Pass it with --conversation-id to continue the thread. Keeping it off standard output means piping the answer into another command no longer carries a trailing ID line you have to strip.
If a conversation can't be resumed, ask tells you why and what to do about it, for the causes it recognizes. Pass --conversation-id a wrong, archived, or already-busy conversation and it says which of the three applies. Run --continue with nothing to resume (no prior conversation, or one saved for a different Bluebox host or workspace) and it tells you to start a new one with a plain bluebox ask. Outside those cases (say your locally saved conversation state can't be read), ask reports the underlying error and asks you to email Bluebox support at support@bluebox.ai if it persists.
Adjusting the response timeout
ask waits a limited time for Bluebox to respond before starting or continuing a conversation. If it times out, the error names which request failed (...the launch request... or ...the resume request...) and means the outcome is unknown, not that nothing happened: Bluebox may already be processing your question. If you were continuing a conversation, asking again may duplicate that turn. Check with --conversation-id first. If you were starting a new one, there is no id to check yet, so asking again simply starts an unrelated conversation.
On a slow or high-latency connection, raise the budget with BLUEBOX_ASK_CONNECT_TIMEOUT (new conversations) or BLUEBOX_ASK_RESUME_TIMEOUT (continuing one), both capped at 10 minutes. See Environment variables.
BLUEBOX_ASK_CONNECT_TIMEOUT=15s bluebox ask "any error rate spikes?"
When you redirect the output to a file or another command, there is no spinner to show, so Bluebox prints a short Asking Bluebox... (30s) progress line to standard error every 15 seconds. That way a long-running question still shows it is working.
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 investigations list
List the investigations in your active workspace.
bluebox investigations list
The table shows each investigation's id, status, and title. One page comes back per call; when more results exist, a "more results available" note tells you so. To see the next page, run --output json, copy the next_cursor value, and run again with --cursor <token>.
| Flag | Description |
|---|---|
--output json | Print the response as JSON — an items array plus next_cursor and total_count. This is the server's response exactly as returned. |
--cursor <token> | Fetch the next page. Pass the next_cursor value from a previous page. |
--workspace <id> | List from a different workspace for this call only. |
bluebox investigations get
Show a single investigation by its id.
bluebox investigations get <id>
Pass the id from bluebox investigations list (a raw UUID also works). The command prints the investigation's details; add --output json for the complete object. An id that does not exist, or one you are not allowed to see, exits with an error.
| Flag | Description |
|---|---|
--output json | Print the investigation as JSON instead of human-readable lines. |
--workspace <id> | Read from a different workspace for this call only. |
bluebox repos list
List the repositories connected to your active workspace.
bluebox repos list
The primary repository is marked with a leading *.
| Flag | Description |
|---|---|
--output json | Print the list as JSON (an items array) instead of a table. |
--workspace <id> | List from a different workspace for this call only. |
bluebox services list
List the services Bluebox knows about in your active workspace.
bluebox services list
One page comes back per call; when more services exist, a "more results available" note tells you so. To see the next page, run --output json, copy the next_cursor value, and run again with --cursor <token>.
| Flag | Description |
|---|---|
--output json | Print the list as JSON. This is the server's response exactly as returned. |
--cursor <token> | Fetch the next page. Pass the next_cursor value from a previous page. |
--workspace <id> | List from a different workspace for this call only. |
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 |
|---|---|
--output json | Print the list as JSON instead of a table (--json is a deprecated alias) |
Under --output json the list comes back as a JSON object with an items array, the same shape bluebox skills list --output json returns:
{
"items": [
{
"id": "…",
"name": "acme",
"display_name": "Acme",
"role": "owner",
"status": "active",
"active": true
}
]
}
If you already script against this command, note that it changed: it used to print a bare array, so a jq '.[]' expression becomes jq '.items[]'.
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. It works on ask, otlp-endpoint, and the read commands investigations list, investigations get, repos list, and services list.
bluebox ask --workspace <id> "any error rate spikes in the last 30 minutes?"
bluebox otlp-endpoint --workspace <id>
bluebox investigations list --workspace <id>
If your saved workspace becomes inaccessible (say 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. |
BLUEBOX_NO_AGENT | Set to 1 to use the interactive CLI even when a coding-agent environment variable is present. Useful if you have more than one coding assistant installed and one of them leaves its environment variable set in your shell. |
BLUEBOX_ASK_CONNECT_TIMEOUT | How long ask waits for Bluebox to respond when starting a new conversation. Takes a duration like 10s or 1m, capped at 10m; defaults to 5s. See Adjusting the response timeout. |
BLUEBOX_ASK_RESUME_TIMEOUT | The same wait, but for continuing an existing conversation with --conversation-id or --continue. Capped at 10m; defaults to 20s, a larger budget since continuing is the request most likely to need it. |
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