CLI reference
Version: 12.4 | Last updated: 2026-11-12
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 / Linux
- Windows — PowerShell
- Windows — Command Prompt
curl -fsSL https://app.bluebox.ai/install.sh | bash
irm https://app.bluebox.ai/install.ps1 | iex
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.
Install in CI
In a pipeline, don't use the installer: it downloads the binary and runs it before anything checks it. Download the binary yourself and check its checksum before it runs and before BLUEBOX_TOKEN is in scope:
os=linux; arch=amd64 # lowercase os; x86_64 is amd64, aarch64 is arm64
meta="$(curl -fsS --proto '=https' "https://app.bluebox.ai/v1/cli/latest?os=$os&arch=$arch")" || { echo "cli metadata fetch failed"; exit 1; }
url="$(printf '%s' "$meta" | jq -er '.download_url')" || exit 1
sum="$(printf '%s' "$meta" | jq -er '.sha256')" || exit 1
mkdir -p "$HOME/.bluebox/bin"
bin="$HOME/.bluebox/bin/bluebox"
curl -fsSL --proto '=https' --proto-redir '=https' -o "$bin" "$url"
echo "$sum $bin" | sha256sum -c - || exit 1
chmod +x "$bin"
export PATH="$HOME/.bluebox/bin:$PATH"
The endpoint serves the CLI of the current Bluebox release, so each run gets the latest version and its checksum. Keep BLUEBOX_TOKEN out of the install step: pass it from your CI secret store only to the step that runs bluebox ask, after the check passes.
Install with npm
If you have Node.js, you can install the CLI as an npm package instead. It works on macOS, Linux and Windows, on x64 and arm64:
npm install -g @bluebox-hq/bluebox-cli
bluebox setup
npm installs only the binary for your platform, as an optional dependency. Don't install with --omit=optional: without that dependency, bluebox stops with an error naming the missing package.
To update an npm install, run the command below; bluebox update prints it instead of replacing the binary.
npm install -g @bluebox-hq/bluebox-cli@latest
To remove it, run bluebox uninstall first to delete what Bluebox stored on your machine, then:
npm uninstall -g @bluebox-hq/bluebox-cli
Install from within your IDE
If you are working inside an IDE, install Bluebox CLI from its built-in terminal. The steps are the same in every IDE; only the coding agent you choose and the folder where its skills land differ.
-
Open your project folder in the IDE, then open a terminal: Terminal → New Terminal. The terminal opens in your project folder, which is where per-repository skills are installed.
-
Run the installer for your platform:
- macOS / Linux
- Windows — PowerShell
- Windows — Command Prompt
curl -fsSL https://app.bluebox.ai/install.sh | bashirm https://app.bluebox.ai/install.ps1 | iexcurl -fsSL https://app.bluebox.ai/install.cmd -o install.cmd && install.cmd && del install.cmdThe installer downloads the CLI, installs it under
~/.bluebox/bin/by default (%USERPROFILE%\.bluebox\binon Windows), and starts setup. On macOS and Linux it first waits with Press enter to start initial setup; press Enter to continue. Setup needs a terminal of at least 80x20, so enlarge the IDE's terminal panel if setup asks you to. These steps describe running the installer yourself. When Bluebox detects that a coding agent is running it, the installer skips the prompt and starts setup without the interactive screens below. -
Work through the setup sections. Press Tab and Shift+Tab to move between sections, and q to quit:
- GitHub sign-in & workspace: sign in through your browser and choose the Bluebox workspace this machine uses. The browser step accepts any sign-in method, including email, so you do not need a GitHub account to finish setup.
- Coding agents & skills—select your coding agent, then choose where its skills are installed: Per-repository (only the repositories you pick in the next section), Globally (shared across all your repositories), or Skip. Agents are labeled supported or experimental. See Supported coding agents.
- Local repositories—check the repositories you work on with Bluebox, or none. With per-repository skills, the checked repositories get the skills. With global or skipped skills, check the repositories relevant for OTel instrumentation.
- Review & finish—check the summary, then choose Exit, or Open in browser & Exit when it is offered, to continue in Bluebox.
-
Confirm the skills are available. In your coding agent's chat, type
/and look for these skills (typing/blueboxfilters the list). To see every Bluebox skill and its installed version, runbluebox skills list:bluebox-investigation-contextbluebox-otel-instrumentationbluebox-overviewbluebox-production-query
Running bluebox setup again is safe and does not create duplicates. It does not update skills that are already installed. If you delete a skills folder Bluebox installed, running setup again reinstalls it. To update them, run bluebox skills refresh.
Where skills are installed
Setup installs each Bluebox skill once for each agent you choose, except in the npx skills add case below. An agent that reads another chosen agent's folder uses that folder instead of getting its own copy:
| Agent | Per-repository | Global |
|---|---|---|
| Claude Code | .claude/skills/ | ~/.claude/skills/ |
| Kiro | .kiro/skills/ | ~/.kiro/skills/ |
| Cursor | .claude/skills/ with Claude Code, else .cursor/skills/ | ~/.claude/skills/ with Claude Code, else ~/.agents/skills/ with GitHub Copilot or OpenCode, else ~/.cursor/skills/ |
| GitHub Copilot in VS Code | .claude/skills/ with Claude Code, else .github/skills/ | ~/.claude/skills/ with Claude Code, else ~/.agents/skills/ |
| OpenCode | .claude/skills/ with Claude Code, else .opencode/skills/ | ~/.claude/skills/ with Claude Code, else ~/.agents/skills/ |
GitHub Copilot CLI does not read ~/.claude/skills/, so with global skills and Claude Code chosen it finds no Bluebox skills. To install them for Copilot CLI, run:
bluebox skills install --generic ~
Cursor, GitHub Copilot in VS Code and OpenCode read both folders, so they then see each skill twice.
When you change your choice of agents, setup removes the copies in folders no longer used. Copies you edited or committed to git stay, and so do files from bluebox skills install.
Skills installed with npx skills add
You can also install the Bluebox skills without the CLI: run npx skills add bluebox-hq/skills to install them from the public bluebox-hq/skills repository.
If you installed them with npx skills add, bluebox setup and bluebox skills install leave them to npx skills and add no second copy. bluebox skills list shows them as npx (bluebox-hq/skills).
- To update these skills, run
npx skills update. - To have
bluebox setupmanage a skill again, runnpx skills remove <name>(add-gfor a global install), then runbluebox setup.
If npx skills add didn't install a skill for Claude Code and you choose Claude Code in setup, setup adds its own copy, so Cursor, GitHub Copilot and OpenCode see that skill twice.
Kiro
Choose Kiro in Coding agents & skills. Restart Kiro so the skills appear as slash commands.
Cursor
Choose Cursor in Coding agents & skills. The skills appear as slash commands automatically—no restart required.
OpenCode in VS Code
Choose OpenCode in Coding agents & skills. OpenCode support is experimental.
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.
After printing the version, it also checks whether a newer release exists and, if so, prints a note suggesting you run bluebox update. This check never delays or changes the version output, and stays silent if it can't reach the server.
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 licenses
Print the license of the bluebox CLI (Apache-2.0) and the licenses and notices of the open-source software it includes.
bluebox licenses
Release archives contain the same text in LICENSE, NOTICE and THIRD_PARTY_NOTICES.
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 a package manager installed the CLI, bluebox update leaves the binary alone and prints the command that updates it through that package manager. It doesn't check Bluebox for a newer version in that case, because the package manager knows which version is current. If Bluebox can't determine how the CLI was installed, it checks for a newer version and, when there is one, prints the installer command for your platform to re-run:
- macOS / Linux
- Windows
A newer version (v1.2.0) is available. Re-run the installer to update:
curl -fsSL https://app.bluebox.ai/install.sh | bash
A newer version (v1.2.0) is available. Re-run the installer to update:
irm https://app.bluebox.ai/install.ps1 | iex
For an npm install, it prints:
bluebox was installed with npm. To update it, run:
npm install -g @bluebox-hq/bluebox-cli@latest
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 uninstall
Remove the local files Bluebox has written: installed coding-agent skills, instrumentation templates, the state and config directories, your stored bearer token, and the CLI binary itself.
bluebox uninstall
Every run first prints an inventory of what it will remove, including any file it can no longer safely remove (see below) and any manual step you still need to take. On an interactive terminal, you can then confirm before anything is actually removed—the default is to cancel.
If a package manager installed the CLI, uninstall leaves the binary in place. The inventory lists the package manager's remove command as a step you still need to take.
For an npm install, that step is:
bluebox was installed with npm. Remove it with: npm uninstall -g @bluebox-hq/bluebox-cli
A file Bluebox installed but you later edited is never deleted or overwritten: it's kept and listed by its full path, both in the initial inventory and in the final summary, so you can decide what to do with it yourself. A file Bluebox installed that's reached only through a symlink is left in place the same way and listed separately. Skills that npx skills add took over stay too, listed under Left to npx skills; remove them with npx skills remove.
Pass --yes to skip the confirmation prompt—required if you're running uninstall from a script or a coding agent, since those don't get an interactive prompt. Pass --dry-run to print the same inventory without removing anything.
bluebox uninstall --yes
bluebox uninstall --dry-run
Exit codes: 0 on success (including a declined prompt or --dry-run). 1 if a removal failed partway through—the command names what's left and is safe to re-run—or if there is no interactive terminal and --yes was not passed.
Get help for a command
Run bluebox help for the full list of commands, and bluebox help <command> for any single command's usage and flags—this form works for every command.
bluebox help ask
bluebox help guided
You can also add --help directly to a command that runs on its own, including a subcommand of a group:
bluebox ask --help
bluebox guided start --help
A command that only groups subcommands together (such as auth or guided) does not take --help itself—use bluebox help <group> to see what it offers.
Help text is printed to standard error, so it never mixes into output you pipe from a command.
Enable shell completion
Generate a completion script for your shell so you can tab-complete commands and flags.
bluebox completion bash
Replace bash with zsh, fish, or powershell for your shell. Run bluebox completion on its own to see the supported shells.
The script is printed to standard output. To turn on completion for your current session, source it directly:
source <(bluebox completion bash)
To load it in every new shell, write the script to your shell's completion directory (the exact location depends on your shell and operating system).
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 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 step at the end of bluebox setup shows your observability-connection status (connected, with its endpoint, or not yet connected) alongside the other setup sections. If you are signed in, the review step also offers a Sign out action, so you can hand this machine to a different account without leaving the setup flow. It also checks for a newer CLI release and shows a note near the top of the screen suggesting you run bluebox update when one is available.
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 Install 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.
Install 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 has its own flag (Claude Code, Cursor, Windsurf, GitHub Copilot, Kiro, Codex, or OpenCode), pass it instead of the generic layout, and combine flags to write more than one convention at once:
bluebox skills install --claude --kiro
Each flag writes its own folder, so pass one flag per folder your agents need. Cursor, GitHub Copilot and OpenCode also read .claude/skills/ and .agents/skills/, and Windsurf reads .agents/skills/. In a repository, --claude alone therefore covers Claude Code, Cursor, GitHub Copilot and OpenCode; adding their flags or --generic gives them each skill twice. To install into your home folder for GitHub Copilot, OpenCode or Windsurf, use --generic.
To see every skill before installing, list them first:
bluebox skills list
Each skill gets one row: name, the version Bluebox serves, the version installed on your machine, and description. The INSTALLED column shows - when a skill is not installed, and lists more than one version when different coding agents hold different copies. Run bluebox skills refresh to bring them up to date. 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. For a skill that npx skills add installed in that directory, it writes nothing into npx's folders and installs no copy for an agent that already reads the npx copy. It lists those skills under Left to npx skills.
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.
A skill may include supporting reference files and scripts alongside its main SKILL.md; these are installed together and refreshed together. When a skill drops or renames one of those files, refresh removes the old file so your coding agent never reads a stale copy, unless a symbolic link stands in the way.
To keep a repository from redirecting skill files elsewhere, Bluebox skips some symbolic links. It skips a skill when the skill's folder, or a file or folder it writes inside that folder, is a symbolic link. In a repository, or a folder you pass to bluebox skills install, it also skips an agent folder such as .claude or .claude/skills that links outside that folder. The global install in your home folder follows those links, so a dotfiles-managed ~/.claude keeps working. An old file behind a skipped link stays on disk and Bluebox stops tracking it, so delete it yourself if you no longer want it.
An older bluebox CLI can't install those supporting files, and the skill's SKILL.md may carry a note saying so. To get them, update the CLI, then refresh - --force reinstalls even when the CLI thinks it's current, and refresh installs any supporting file that is missing, even when the skill's version hasn't changed:
bluebox update --force
bluebox skills refresh
A CLI too old to have bluebox update needs the installer at the top of this page instead.
Refresh lists a skill it reinstalled at the version you already have under Repaired, with the reason, for example supporting files that were never installed or a skill file that went missing. Skills that moved to a new version are listed under Updated.
| 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, or if a skill failed to install — rerun the command to retry.
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. If you are not signed in, Bluebox asks you to sign in first with any sign-in method you use, and to accept the Terms of Service if you are new; you then return to the approval step. The token is stored securely in your OS keyring (macOS Keychain, Linux Secret Service), with an access-restricted file as fallback.
The approval page shows the Device, Software and Network address that asked for access. Check them against your terminal before you approve, and deny the request if any of them is unfamiliar. When the request came from a different network address than your browser, for example over a VPN or from a remote machine, tick the box confirming you started it yourself; without it, Authorize is refused. A request from a network that your Bluebox administrators have marked as a hosted service is refused; by default no network is marked. If you have ten approved sign-ins that have not finished, approval waits until they complete or expire.
| 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. Re-running login revokes the token it replaces.
A sign-in token can be limited to what the CLI does: its own commands and the Bluebox MCP server. Where that limit is on, Bluebox refuses the token elsewhere with 403. To call other Bluebox APIs from a script, create a token under Account → Access tokens and pass it in BLUEBOX_TOKEN.
bluebox auth logout
Clear stored credentials.
bluebox auth logout
After signing out, 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 24 h when omitted; a continued conversation keeps the window an earlier question set. |
--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, but only when that repository is connected to the workspace. Use --repo-url to override the detected value.
ask reads files, pull requests, their diffs, and issues in your connected repositories. It reads the GitHub copy on the default branch unless you name another branch, so changes you have not pushed are not visible to it. It never reads secret-bearing files such as .env or private keys. From your local checkout, the CLI sends only the repository URL, your working directory, and the modules you changed. The Evidence section of the answer lists the files it read.
Ask 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.
Read 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.
Stop a question
Press Ctrl+C twice while ask runs. After the first press, ask shows "Press Ctrl+C again to cancel" below its progress until you press it again. Bluebox then stops the investigation, so it stops counting toward your usage. Usage already spent stays counted. If Bluebox doesn't confirm the stop within a few seconds, ask exits anyway and warns that the investigation may keep running. To quit without waiting, press Ctrl+C once more.
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.
On a terminal that supports links, the printed ID is a clickable link that opens the conversation in the Bluebox web UI; the text stays the bare ID, so copying it still works. When output is redirected, color is disabled, or the workspace can't be determined, the plain ID is printed with no link.
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. If an approval in that conversation is still waiting for a decision, ask says so and tells you to decide it in the Bluebox UI and then continue. 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.
Continue with the same scope
A continued conversation keeps the scope of its previous question. Any of --service, --env, --entity-id, --task-id, and --since that you leave off carries over, so bluebox ask --continue "and the error rate?" answers about the same service and time window as before. Pass a flag to change just that part of the scope:
--entity-idreplaces an earlier--serviceand--env, and either of those replaces an earlier--entity-id.- Continuing from a different repository drops the earlier service and entity.
To drop the scope entirely, start a new conversation with a plain bluebox ask.
Adjust the response timeout
ask waits a limited time for Bluebox to respond before starting or continuing a conversation. If it times out, or the response is lost on the way back, ask stops the question on Bluebox, so it doesn't keep counting toward your usage. The error names which request timed out (...the launch request... or ...the resume request...) and says asking again is safe.
If ask can't confirm the stop, the error says the outcome is unknown: 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 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?"
While a question runs, the progress line shows what Bluebox is working on. If Bluebox has planned the work, you see the current step and how many steps are done, for example [2/4] Check latency... (95s). Otherwise you see Bluebox's own short description of what it is doing, or what it is checking at that moment, for example Querying logs. Once a step has taken 30 seconds or more, the line also shows how long that step has run, for example (95s, 40s on this step), so a slow step is distinguishable from a stuck one.
When you redirect the output to a file or another command, there is no spinner to show, so Bluebox prints the same progress to standard error as plain lines: one every 15 seconds, plus one soon after the activity changes (at most one every 2 seconds).
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: the URL, nothing else.
bluebox otlp-endpoint
This is the endpoint your services send telemetry to. The Bluebox instrumentation skill runs this command itself unless your environment already exports the endpoint. 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. In the last two cases it also shows your installed CLI version and, if a newer release exists, asks you to run bluebox update first: an outdated CLI can report a setup problem on a workspace that is already connected.
The command never prints your ingest token. Copy it from Settings → Setup in the web app instead, as Get started describes: select Instrument your services in the step list, then click Reveal token and Copy token next to Ingest token. Bluebox keeps it out of the CLI so a coding agent never sees it. Where you put it is yours to choose: a secret manager, or an env file that stays git-ignored.
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
| 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>. If you used --search, pass the same --search again, or the next page comes from the unfiltered list.
| Flag | Description |
|---|---|
--search <text> | List only services whose name contains the text, ignoring case. Works with --cursor and --output json. |
--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.
Connect your coding agent
Some coding agents can call Bluebox directly with a CLI token — see BLUEBOX_TOKEN below.
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 Adjust 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