Guides · Install

Install

Four packages, two registries, no installer script. This page covers getting each one onto a machine, pinning it, verifying it, upgrading it, removing it, and running the CLI in CI.

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.10 and newer.

PackageWhat it is forNeedsFrom
@bearlumen/node-sdkTrack AI calls and read costs from Node.js or TypeScript.Node.js 20 or newernpm
bearlumenTrack AI calls and read costs from Python.Python 3.10 or newerPyPI
@bearlumen/cliQuery costs, margins, and usage from a terminal or CI.Node.js 20 or newernpm

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

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

Python SDK

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

CLI

bash
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

JSON
# Nothing to install. Point the client at the hosted endpoint and sign in:
{
  "mcpServers": {
    "bear-lumen": {
      "type": "http",
      "url": "https://api.bearlumen.com/mcp"
    }
  }
}

The MCP server page covers connecting Claude, ChatGPT, Claude Code and other MCP clients, signing in, and using an API key instead.

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 MCP server is the exception: it is hosted at https://api.bearlumen.com/mcp, so there is no version to pin.

bash
# 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

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.

bash
$ 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

bash
# 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: nothing to upgrade. It is hosted, and its tools change when
# Bear Lumen deploys.

Read the changelog before a minor bump

Breaking changes are listed first in each changelog entry with the step to take. A patch release never needs one.

Uninstall

bash
# 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: remove the "bear-lumen" connector from the client. Nothing was
# installed, so nothing else is left behind.

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: the Node SDK and the CLI are npm packages, and the MCP server needs no install at all. 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