crossbeam-cli

CLI client for Crossbeam. Log in with your existing Crossbeam credentials and read your partners, populations, overlaps, reports, account-mapping data, and more — from your terminal.

🌐 Website & one-click Claude Desktop extension →

Free for any Crossbeam customer. Crossbeam normally requires upgrading to a paid tier (Connector / Supernode) to access their public API. This package uses the same endpoints the Crossbeam web app itself uses, so anyone with a Crossbeam login — including users on the free plan — can pull their own data programmatically.

Great for AI agents. Plug your partner ecosystem data into Claude Code, Cursor, or any agent framework. See the AI agent prompt below.

⚠️ This package talks to Crossbeam's internal api.crossbeam.com endpoints (the same ones the Crossbeam web app uses). It is not affiliated with or endorsed by Crossbeam, Inc. Use at your own risk.

Installation

npm install --save crossbeam-cli
# or globally for the CLI binary:
npm install --global crossbeam-cli

The CLI binary is named crossbeam.

Claude Desktop (MCP bundle)

The same Crossbeam API is also available to Claude Desktop as an MCP server, packaged as a one-click .mcpb bundle.

⬇️ Download crossbeam.mcpb

Install:

1. Download crossbeam.mcpb (always the latest version).
2. In Claude Desktop, open Settings → Extensions and drag crossbeam.mcpb onto the window (or Install Extension → choose file).
3. When prompted, enter your Crossbeam email and password (and optionally an organization id). Your password is stored in your OS keychain by Claude Desktop and is passed to the server as an environment variable — it is never sent anywhere except auth.crossbeam.com at login.

Claude can then call read tools like list_partners, get_account_mapping, get_overlap, get_report_data, search, and a get escape hatch for any other endpoint. The full tool list is declared in manifest.json.

The MCP server is read-only and uses the exact same login + session caching as the CLI (~/.crossbeam/session.json). Credentials and data stay on your machine.

Use it from other MCP clients (Claude Code, Cursor, etc.) without the bundle by running the server directly over stdio after installing the package:

// e.g. Claude Code: claude mcp add, or any client's mcpServers config
{
  "command": "npx",
  "args": ["-y", "crossbeam-cli", "crossbeam-mcp"],
  "env": {
    "CROSSBEAM_USERNAME": "you@example.com",
    "CROSSBEAM_PASSWORD": "your-password",
    "CROSSBEAM_ORG": ""
  }
}

Build the bundle yourself:

npm install
npm run pack:mcpb   # → crossbeam.mcpb

This bundles src/mcp.ts and its dependencies into a single self-contained file under build/mcpb/ and packs it with @anthropic-ai/mcpb.

How it works

crossbeam-cli is a thin wrapper around Crossbeam's private HTTP API — the same endpoints the Crossbeam web app calls when you're signed in. When you run a command:

1. You provide your own Crossbeam username and password (via flag, env var, or interactive prompt).
2. The package logs in to auth.crossbeam.com, gets a session cookie, and stores it at ~/.crossbeam/session.json (mode 0600, valid for 6 hours).
3. Every API call goes directly to api.crossbeam.com over HTTPS with that cookie.

Your Crossbeam credentials and your Crossbeam data never leave your machine. This package has:

• No backend, proxy, or relay — every API call goes straight to api.crossbeam.com.
• No third-party HTTP libraries for Crossbeam calls — just Node's built-in fetch.
• No remote configuration or auto-updates.

Usage monitoring

To understand who is using the tool, crossbeam-cli sends basic usage analytics to PostHog: your login email and the name of the command (or MCP tool) you run (plus the tool version). That's it — no command arguments, no passwords, no session cookies, and none of your Crossbeam data (partners, populations, accounts, overlaps, reports) are ever sent.

Opt out completely by setting either environment variable:

export CROSSBEAM_NO_TELEMETRY=1   # or: DO_NOT_TRACK=1

The full source is in src/ — read it, audit it, fork it. The monitoring lives in src/telemetry.ts.

AI agent prompt

crossbeam-cli is built for AI coding agents (Claude Code, Cursor, Cline, Aider, Codex, etc). Every command emits JSON with --json, and the crossbeam raw <METHOD> <path> escape hatch lets an agent hit any endpoint it discovers.

Drop the prompt below into Claude Code / Cursor / your agent of choice to give it everything it needs:

You have access to a CLI called `crossbeam` (npm package: `crossbeam-cli`) that
reads data from the user's Crossbeam account. Use it to answer questions about
their partners, ecosystem, populations, account-mapping records, and overlaps.

Setup (do this once per shell):
- Install: `npm install -g crossbeam-cli`
- Auth: ask the user for their Crossbeam email + password and export them as
  CROSSBEAM_USER and CROSSBEAM_PASS. Sessions are cached for 6 hours at
  ~/.crossbeam/session.json, so you only need credentials on the first run.

Always pass `--json` so output is machine-readable. Pipe through `jq` to keep
context small. Examples:

  crossbeam me --json | jq '.user.email, .authorizations[0].organization.name'
  crossbeam partners list --json | jq '.items[] | {id, name, domain}'
  crossbeam populations list --json | jq '.items[] | {id, name, record_count}'
  crossbeam overlap <partner-id> --json | jq '.items | length'
  crossbeam account-mapping --our-segment customer --limit 100 --json
  crossbeam report-data --partner 1234,5678 --type ecosystem --limit 200 --json
  crossbeam raw GET /v0.1/team --json    # any internal endpoint

Discovery:
- `crossbeam endpoints --json` lists every command and its arguments.
- `crossbeam --help` prints full CLI help.

Programmatic use (TypeScript / Node):

  import { CrossbeamClient } from "crossbeam-cli";
  const c = await CrossbeamClient.login({
    username: process.env.CROSSBEAM_USER!,
    password: process.env.CROSSBEAM_PASS!,
  });
  const partners = await c.listPartners();
  const overlap  = await c.getOverlap(partners[0].id);

Important rules:
- Never print or log the user's password.
- Prefer the cached session — do NOT pass `--fresh-login` unless you see a
  401/403 error.
- For large result sets, use `--limit` and `--page` for pagination.
- If the user asks for data the existing commands don't expose, use
  `crossbeam raw GET <path>` to call internal endpoints directly.

CLI usage

crossbeam <command> [subcommand] [args] [options]

Authentication

Provide credentials by flag. First run logs in; subsequent runs reuse the cached session (see How it works).

crossbeam me --user you@example.com --pass 'your-password'

# or via env:
export CROSSBEAM_USER=you@example.com
export CROSSBEAM_PASS='your-password'
crossbeam partners list

If --pass and CROSSBEAM_PASS are both missing, the CLI prompts for the password silently on a TTY.

Flags:

Flag	Description
--user, -u	Crossbeam username
--pass, -p	Crossbeam password
--org <id>	Override organization id (defaults to your first authorized org)
--json	Print raw JSON instead of a pretty table
--no-cache	Don't read or write the session cache
--fresh-login	Force a fresh login this run (skip the cached session)
logout	Forget cached session(s)

Commands

Run crossbeam endpoints for the full list. Highlights:

crossbeam me                                     # current user + org
crossbeam team                                   # list org members
crossbeam partners list                          # all partners with overlap counts
crossbeam partners get <id|uuid>
crossbeam partners users <id|uuid>
crossbeam partners overlap-matrix <id|uuid>
crossbeam populations list [--inactive]
crossbeam reports                                # saved Account-Mapping views
crossbeam lists                                  # user-saved lists
crossbeam overlap <partner-id>
crossbeam report-data --partner 1234 --type ecosystem --limit 100
crossbeam account-mapping --our-segment customer --limit 100
crossbeam search "<query>"
crossbeam clearbit "<query>"
crossbeam raw GET /v0.1/team                     # call any endpoint

---

Programmatic usage

import { CrossbeamClient } from "crossbeam-cli";

const client = await CrossbeamClient.login({
  username: process.env.CROSSBEAM_USER!,
  password: process.env.CROSSBEAM_PASS!,
  // org: "12345",       // optional: override organization id
  // useCache: true,      // default: true. Reads/writes ~/.crossbeam/session.json
});

const me = await client.getMe();
console.log(`Logged in as ${me.user?.email}`);

const partners = await client.listPartners();
for (const p of partners) {
  console.log(`${p.id}\t${p.name}\t${p.domain ?? ""}`);
}

const overlap = await client.getOverlap(partners[0].id);
console.log(`Overlap with ${partners[0].name}: ${overlap.items?.length ?? 0} rows`);

CrossbeamClient.login(options)

type LoginOptions = {
  username: string;
  password: string;
  org?: string;          // override organization id
  useCache?: boolean;    // default true; caches at ~/.crossbeam/session.json
  forceFreshLogin?: boolean;
};

Selected client methods

All methods return parsed JSON. See src/client.ts for the full surface.

Area	Methods
Identity	getMe(), getTeam(), getRoles(), getPermissions(), getFeatureFlags()
Partners	listPartners(), getPartner(id), getPartnerUsers(id), getPartnerTags(id), getPartnerTeamAccess(id), getPartnerSuggestions(), getOverlapCounts(), getPartnerFavorites(), getPendingShareRequests()
Populations	listPopulations({ onlyInactive? }), getPopulationStats(), getPopulationRecordStats(), listPartnerPopulations(), listPartnerTags()
Reports	listLists(), listReports(), listReportFolders(), getReportData(body, { page, limit }), getAccountMapping(opts), getPartnerSources(body)
Sources	listSources({ includeDeleted? }), getSource(id), listFeeds(), getFeed(id), listConnections()
Sharing	getInboundShareRequests(), getOutboundShareRequests(), getIncomingShareRules(), getOutgoingShareRules(), getIncomingDataShares(), getOutgoingDataShares(), listSharePresets()
Overlaps	getOverlap(partnerId), getOverlapTotal(partnerId, populationIds?), getOverlapMatrix(partnerId)
Misc	discoverOrgs(query), clearbitAutocomplete(query), search(query), listIntegrations(), listNotifications(), getNotificationSettings(), getAttribution(kind), listFileUploads(), listFileUploadTables(), getMopOrganizations(), getMopPartnerships()
Escape hatch	get<T>(path, query?), post<T>(path, body?)

Session caching

CrossbeamClient.login() caches cookies at ~/.crossbeam/session.json (mode 0600) for 6 hours, keyed by username. Set useCache: false to skip, or forceFreshLogin: true to bypass on this call only. To clear everything programmatically:

import { clearSession } from "crossbeam-cli";
clearSession();              // clear all
clearSession("you@x.com");   // clear one user

Development

npm install
npm run build
node dist/cli.js me --user you@x.com --pass '...'
npm pack --dry-run         # see what would ship

Disclaimer

Unofficial client. Crossbeam may change or block these endpoints at any time. Use at your own risk.

License

BSD 4-Clause License. Free for any use — including commercial — provided the advertising clause is honored.

Required attribution. Any advertising material mentioning features or use of this software must display:

"This product includes software developed by Ryan Hughes (Fan Pier Labs, https://fanpierlabs.com)."

See ATTRIBUTION.md for drop-in snippets (plain text, Markdown, HTML) and the full list of materials this applies to. A commercial license without the advertising clause is available — contact ryan@fanpierlabs.com.