AI Agents

CLI

The bearlumen CLI gives you the same AI cost intelligence as the MCP server, from your terminal. Human-readable tables by default, raw JSON for piping to jq, and a command for every MCP tool.

Install

npm install -g @bearlumen/cli
# or run without installing:
npx @bearlumen/cli --help

Authenticate

Set your API key once (create one at app.bearlumen.com/settings/api-keys), or pass --api-key per command. Use --base-url to target a non-production host.

export BEAR_LUMEN_API_KEY="your-api-key-here"

Usage

bearlumen ping                       # verify key + connectivity
bearlumen cost summary               # spend now vs previous period
bearlumen cost by-model --start 2026-06-01 --end 2026-06-30
bearlumen cost by-dimension workflow # any axis: agent, workflow, custom key
bearlumen margin by-end-user
bearlumen insights --limit 5
bearlumen usage summary
bearlumen dimensions

Run bearlumen <command> --help for the options of any command.

Dates and windows

--start / --end accept ISO YYYY-MM-DD. Omit them and the command defaults to the trailing 30 days, the same default the MCP server uses.
cost summary takes --window instead (7d, 30d, 90d, mtd) and already returns a period-over-period comparison.

JSON output

Add --json to emit raw JSON instead of a table, for piping:

bearlumen cost by-model --json | jq '.items | max_by(.total_cost)'
bearlumen margin by-end-user --json | jq '.end_users[] | select(.margin_amount < 0)'

Parity with the MCP server

Every CLI command maps to one MCP tool and back. An agent and a shell script see identical data. If a command exists here, the matching tool exists there.

Exit codes

0 on success, 1 on any error. API errors print a code, status, and a ref correlation id to stderr, so failures are easy to script around and to quote in a support request.