SDK Installation & Quick Start

Use busabase-sdk to connect a TypeScript or JavaScript app to Busabase. It uses the same API, base URL, credentials, and workspace selection as the CLI.

Install

Use Node.js 24.18.0 or later, as required by the SDK package. The package ships ES modules and TypeScript declarations.

npm install busabase-sdk

Or use pnpm add busabase-sdk in a pnpm project.

Configure the connection

On Cloud, create a read API key and set the workspace id, or sign in with the CLI and choose the workspace with busabase-cli space use.

The SDK reads environment variables, but does not load ~/.busabase/.env automatically. If you use the CLI's saved configuration, load it when starting Node as shown below.

First read

Create quickstart.mjs in your project:

import { Busabase } from "busabase-sdk";

const bb = new Busabase();
console.log(await bb.health());
console.log(await bb.bases.list());

Run it with the CLI's saved configuration:

node --env-file="$HOME/.busabase/.env" quickstart.mjs

If your environment already contains the connection variables, run node quickstart.mjs. Expect a health response and the Bases visible to your key in the selected workspace. This example only reads data.

Local / Desktop

With a local server running, use an explicit base URL:

import { Busabase } from "busabase-sdk";

const bb = new Busabase({ baseUrl: "http://localhost:15419" });
console.log(await bb.bases.list());

The open-source local server requires no authentication by default. For a self-hosted server, set baseUrl to your team's URL and supply the credentials your deployment requires.

Continue

The SDK exposes namespaced methods such as bb.bases, bb.records, bb.nodes, and bb.changeRequests. Use Change Requests for proposed edits. Browse request and response shapes in the generated API reference, and use REST API when integrating another language.

Keep API keys in your server environment. For an agent connection, consider MCP with OAuth; for agent instructions, install Agent Skills.

Other ways to connect: Integration overview · CLI · SDK · MCP · OpenAPI / REST · Agent Skills · Webhooks