Install

Prerequisites

Every Node package needs Node.js 20 or newer: the SDK signs requests with WebCrypto, and the CLI signs in with the built-in fetch, both of which shipped in Node 20. The Python SDK supports Python 3.9 and newer.

Install each package

npm and pip are the reference commands. The yarn and pnpm equivalents are on the comment line under each one.

Node.js SDK

npm install @bearlumen/node-sdk
# yarn add @bearlumen/node-sdk    |    pnpm add @bearlumen/node-sdk

Python SDK

pip install bearlumen
# or, in a project that uses one: poetry add bearlumen  |  uv add bearlumen

CLI

npm install -g @bearlumen/cli
# yarn global add @bearlumen/cli   |   pnpm add -g @bearlumen/cli
# or run it without installing anything:
npx @bearlumen/cli ping

A global install puts bearlumen on your PATH. npx downloads it into a cache the first time and reuses it after that, which is the right shape for a one-off check or a CI job. Then sign in.

MCP server

# Nothing to install by hand. The MCP client launches it through npx:
{
  "mcpServers": {
    "bear-lumen": {
      "command": "npx",
      "args": ["-y", "@bearlumen/[email protected]"],
      "env": { "BEARLUMEN_API_KEY": "your-api-key-here" }
    }
  }
}

The MCP server page has the exact block for Claude Desktop, Cursor, and Claude Code, plus the hosted remote server for agents that do not run on your machine.

Version pinning

Every package follows semantic versioning and is pre-1.0, so a minor bump can carry a breaking change; the changelog calls each one out with a migration step. Pin what you deploy. The one place pinning is not optional is an MCP config: an unpinned npx -y @bearlumen/mcp-server resolves the newest version on every client launch, so a release would change your agent's tools without you choosing it.

# package.json: a caret range takes patch and minor updates, an exact
# version takes none. Both SDKs are pre-1.0, where a minor bump may carry a
# breaking change, so pin exactly if you deploy from a lockfile-free build.
# The current version of every package is at the top of /changelog.
"dependencies": { "@bearlumen/node-sdk": "0.17.0" }

# requirements.txt / pyproject.toml
bearlumen==0.15.0

# A globally installed CLI is pinned at install time:
npm install -g @bearlumen/cli@0.3.0

# An MCP config is pinned in the npx argument (see above):
"args": ["-y", "@bearlumen/[email protected]"]

Verify

bearlumen ping checks the install, the key, and what the key can do in one call. It exits 0 only when the key has every query scope; a key that is missing one is named, with the preset to select, and the exit code is 1. For an SDK, the quickstart's first tracked event is the equivalent check.

$ bearlumen ping
Connected to acme-inc as "CLI on blaise-mbp" (live)
Scopes: costs:read, revenue:read, usage:read, dimensions:read
Expires: 2026-12-06

$ bearlumen --version
0.3.0

Upgrade

# CLI
npm update -g @bearlumen/cli            # within the installed range
npm install -g @bearlumen/cli@latest    # newest release, whatever the range

# SDKs
npm install @bearlumen/node-sdk@latest
pip install --upgrade bearlumen

# MCP server: edit the pinned version in the client config, then restart
# the client. npx fetches the new version on the next launch.
"args": ["-y", "@bearlumen/[email protected]"]

Uninstall

# Revoke the stored key first, so nothing is left behind on the server.
bearlumen logout

npm uninstall -g @bearlumen/cli
rm -rf ~/.config/bearlumen            # the credentials file, if login was used

npm uninstall @bearlumen/node-sdk
pip uninstall bearlumen

# MCP server: delete the "bear-lumen" entry from the client config and restart
# the client. npx keeps a copy in its cache; clear it with:
npx clear-npx-cache

Removing a package never revokes a key. If you created one by hand for the CLI or the MCP server, revoke it from the API Keys page when you are done with it.

Using the CLI in CI

There is no browser in CI, so skip login: create a key with the CLI and MCP (read-only) preset, store it as a secret, and pass it with --api-key (or export BEARLUMEN_API_KEY). Add --json so the output is stable for jq, and pin the version in the npx call so the job does not change under you.

# .github/workflows/cost-check.yml
jobs:
  cost-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - name: Spend this week vs last
        run: |
          npx @bearlumen/cli@0.3.0 cost summary --window last-7-days --json \
            --api-key "$BEARLUMEN_API_KEY" > summary.json
          jq '.change_percent' summary.json
        env:
          BEARLUMEN_API_KEY: ${{ secrets.BEARLUMEN_API_KEY }}

A read-only key cannot send events, so the worst a leaked CI secret can do is read your cost data; rotate it from the API Keys page if that happens. Keys created by hand have no expiry unless you set one, which is what you want for a scheduled job.

Why there is no shell installer

Many CLIs ship a curl ... | sh script. Bear Lumen does not, for two reasons that are about the product, not about effort.

First, npm is already the integration surface. Every MCP client launches servers through npx, so the MCP server has to be an npm package, and the CLI is the same code behind a different entry point. A second distribution channel would be a second artifact to version, sign, and keep in step, and a second thing you would have to trust.

Second, the CLI is stateless by design. It keeps one file, ~/.config/bearlumen/credentials.json, and nothing else: no daemon, no update checker, no shell integration. There is nothing for an installer to set up that npm install -g does not, and npx @bearlumen/cli runs it with no install at all.

Next steps