Developers

fabplane CLI

fabplane-cli is the open-source command line, MCP server and TypeScript client for the fabPlane API. Use it to keep shopping carts and team inventory in sync from a terminal, a CI job or an AI coding agent. Source and releases: github.com/fabPlane/fabplane-cli (current package version 0.3.0).

Install

Node.js 20 or newer. Until the first npm release, build from source (npm's global git install does not have TypeScript available for the build):

git clone https://github.com/fabPlane/fabplane-cli && cd fabplane-cli
npm ci && npm pack && npm i -g ./fabplane-cli-*.tgz
fabplane --help

After the first npm release, npm i -g fabplane-cli will install the fabplane command, and npx fabplane-cli … will work without a global install.

Sign in

fabplane login

The CLI prints a code and opens the approval page; approve it while signed in to fabPlane. Credentials are written atomically with mode 0600 to $XDG_CONFIG_HOME/fabplane/credentials.json (default ~/.config/fabplane/credentials.json; %APPDATA%\fabplane\credentials.json on Windows). The file keeps one profile per API origin. Override the path with FABPLANE_CREDENTIALS_FILE.

Password login (fabplane login --email … --password …) exists only for local and staging accounts and is refused against production. For CI and servers, create a personal API token in the dashboard and use environment variables instead:

VariableMeaning
FABPLANE_TOKENAn fpk_… API token, fpd_… device token, or fpb_… bot token
FABPLANE_API_ORIGINAPI server, default https://api.fabplane.com
FABPLANE_ORGDefault organization id or slug for commands and MCP tools
FABPLANE_CREDENTIALS_FILEOverride the credentials file path

Resolution order: token from FABPLANE_TOKEN then the credentials file; origin from --origin, then FABPLANE_API_ORIGIN, then the origin you last logged in to; org from --org, then FABPLANE_ORG, then fabplane orgs use, then your personal org.

Commands

Every command takes --json, --org <id|slug> and --origin <url>. Run fabplane help <command> for the rest. Exit codes: 0 success, 1 API or runtime error, 2 usage error.

CommandWhat it does
fabplane login [--token fpk_…] [--origin URL] [--no-browser]Sign in (browser device flow, or store a personal API token). Staging/local also accept --email / --password.
fabplane logout [--origin URL]Forget stored credentials (and revoke a device session).
fabplane whoamiShow the signed-in user, API origin and default org.
fabplane dashboard [--open]Print (or open) the web dashboard URL for the current API.
fabplane orgs listList your orgs (* = default).
fabplane orgs create <name> [--slug slug]Create an org (you become owner).
fabplane orgs use <id|slug>Set the default org for this API origin.
fabplane orgs members [--org id|slug]List members of the org.
fabplane orgs invite [--email addr] [--role member|admin] [--days n]Create an invite link (admin). No email is sent.
fabplane orgs invites [--org id|slug]List pending invites (admin).
fabplane orgs role <userId> <owner|admin|member>Change a member's role (admin).
fabplane orgs accept <invite-token|invite-url>Accept an invite.
fabplane orgs joinableOrgs you can join via your verified email domain.
fabplane orgs join <id>Join an org through its email-domain join.
fabplane tokens listList personal API tokens.
fabplane tokens create <name> [--days n]Create a personal API token (shown once).
fabplane tokens revoke <id>Revoke a personal API token.
fabplane destinations list [--org id|slug]List purchase destinations (built-in + custom).
fabplane destinations add --name NAME --url URL [--kind fab|distributor|manual] [--base builtin:digikey]Add a custom destination (admin).
fabplane carts list [--repo URL] [--project ID]List carts, optionally by repo or project.
fabplane carts show <cartId>Show a cart and its items.
fabplane carts create <name> [--repo URL ...] [--project ID] [--notes TEXT] [--fab builtin:jlcpcb]Create a cart. Items without a destination go to the cart's fab house.
fabplane carts add <cartId> --mpn MPN --qty N [--dest ID] [--manufacturer M] [--description D] [--refs R1,R2] [--sku S] [--url U] [--price P --currency USD] [--kind part|pcb|other] [--notes T]Add one item to a cart.
fabplane carts import <cartId> <file.json|file.csv|-> [--replace] [--source NAME]Add (or with --replace, replace) cart items from JSON, JSONL or a BOM CSV.
fabplane carts export <cartId> [--dest ID] [--output file.csv]Export a cart as CSV (optionally one destination). -o is an alias for --output.
fabplane carts delete <cartId>Delete a cart.
fabplane inventory list [--q TEXT] [--category C] [--location L] [--tag T] [--limit N] [--cursor C] [--all]List/search inventory.
fabplane inventory show <id>Show one inventory item.
fabplane inventory add --name NAME [--mpn M] [--manufacturer M] [--sku S] [--category C] [--description D] [--qty N] [--unit pcs] [--location L] [--tag T ...] [--attr k=v ...] [--source S] [--external-id ID] [--image path ...] [--server-ai]Add an inventory item (optionally with photos).
fabplane inventory import <file.jsonl|-> [--source NAME]Bulk upsert items from JSONL (500 per request, keyed by externalId).
fabplane inventory adjust <id> <delta> [--reason TEXT]Add/subtract stock atomically (e.g. -5).
fabplane inventory delete <id>Delete an inventory item and its images.
fabplane inventory photos queue [--all] [--limit N] [--cursor C]Items waiting for a photo, with counts (--all adds leased and skipped ones).
fabplane inventory photos claim [--limit N] [--lease SECONDS] [--worker NAME]Lease items to find photos for (default 5 for 900 s).
fabplane inventory photos attach <itemId> (--url IMAGE_URL | --file PATH) [--source-url PAGE_URL] [--source web] [--timeout SECONDS]Download (or read) a photo, check it, and upload it to the item.
fabplane inventory photos skip <itemId> [--note TEXT] [--lease-token T]No photo can be found: take the item out of the queue.
fabplane inventory photos retry <itemId> [--note TEXT] [--lease-token T]Give up the lease; the item stays queued for another attempt.
fabplane inventory photos requeue <itemId>Put a skipped item back in the queue (admin).
fabplane bot connect [--name NAME] [--org SLUG] [--agent openclaw|hermes|fabdesk|ci|other] [--origin URL] [--no-browser]Connect this machine as a bot: an org admin approves a link.
fabplane bots list [--org id|slug]Bot members of the org (admin).
fabplane bots create <name> [--role member|admin] [--agent KIND]Create a bot and print its token once (headless setups).
fabplane bots rotate <botId>Issue a new bot token (revokes the old ones).
fabplane bots remove <botId>Delete a bot and revoke its tokens.
fabplane mcp [--desktop]Run the stdio MCP server (for Claude Code, Codex, Cursor…).
fabplane desktop statusIs the fabPlane desktop app running? (reads daemon.json)
fabplane desktop projectsList fabdesk projects.
fabplane desktop toolsList fabdesk tools.
fabplane desktop call <tool> [json-args] [--project ID] [--sync]Call a fabdesk tool.
fabplane api <METHOD> <path> [json|-] [--anonymous]Raw authenticated request (escape hatch).
fabplane versionPrint the version.
fabplane help [command]Show help.

MCP server for Claude Code, Codex and Cursor

fabplane mcp speaks MCP over stdio and uses the same credentials as the CLI. It exposes these tools: org_list, destination_list, cart_list, cart_get, cart_create, cart_add_items, cart_update_item, cart_remove_item, inventory_search, inventory_add, inventory_adjust, inventory_photo_queue, inventory_photo_claim, inventory_photo_attach, inventory_photo_release. fabplane mcp --desktop also adds desktop_status, desktop_projects, desktop_call_tool, which reach the fabPlane desktop app on this machine.

Until the first npm release, point MCP clients at the fabplane binary from a from-source or global install. npx -y fabplane-cli cannot resolve an unpublished package.

Claude Code

claude mcp add fabplane -- fabplane mcp
# with a token and the desktop tools:
claude mcp add fabplane -e FABPLANE_TOKEN=fpk_… -- fabplane mcp --desktop

Codex

Add to ~/.codex/config.toml:

[mcp_servers.fabplane]
command = "fabplane"
args = ["mcp"]
# env = { FABPLANE_TOKEN = "fpk_…", FABPLANE_ORG = "my-team" }

Cursor

Add to .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "fabplane": { "command": "fabplane", "args": ["mcp"] }
  }
}

Other MCP clients

{
  "mcpServers": {
    "fabplane": { "command": "fabplane", "args": ["mcp"] }
  }
}

Bots for agents

Give an agent (openclaw, Hermes, a CI job) its own identity instead of your login. On the agent's machine:

npm i -g fabplane-cli
fabplane bot connect --agent openclaw --name "openclaw on bench-pc"

--name is optional; the default is <agent or fabplane-cli> on <hostname>. The CLI prints a link and a code. Open the link while signed in, pick the organization and role, and approve; the CLI then stores the bot token (fpb_…) with that org as its default. fabplane whoami shows kind: bot. A bot can work on carts, inventory and the photo queue of its own org only; it cannot create orgs, invite people, make API tokens or manage other bots. For headless machines an admin can instead run fabplane bots create <name> (or use the dashboard's Bots section) and set the printed token as FABPLANE_TOKEN. Ready-made skills live in the fabplane-cli repository under integrations/openclaw/ and integrations/hermes/.

Library

Every API operation is a method on FabplaneClient, named after its operationId. Errors throw FabplaneApiError with status and code.

import { FabplaneClient, FabplaneApiError, resolveDefaultOrg, dashboardUrlFor } from "fabplane-cli";

const client = new FabplaneClient({ token: process.env.FABPLANE_TOKEN });
const org = await resolveDefaultOrg(client);

const { cart } = await client.createCart(org, { name: "Rev B", repos: ["https://github.com/acme/board"] });
await client.replaceCartItems(org, cart.id, [
  { kind: "pcb", description: "Main board", quantity: 5 },
  { mpn: "LM1117-3.3", quantity: 5, destinationId: "builtin:digikey" },
], "my-script");

await client.createInventoryItem(org, { name: "ESP32-S3 module", quantity: 12, location: "drawer A3" });
console.log(dashboardUrlFor(client.origin));

The package also exports fabplaneTools (the MCP tool definitions, for embedding in your own agent), dashboardUrlFor(apiOrigin), DEFAULT_API_ORIGIN, resolveAuth, CredentialStore and FabdeskClient for talking to a local fabdesk desktop daemon.

Staying in sync with the API

The server publishes an OpenAPI 3.1 document at /v1/public/openapi.json, generated from its request schemas. The fabplane-cli repository's Sync API spec workflow runs every Monday at 03:00 UTC: it saves the document to spec/openapi.json, regenerates the operation list and opens or updates a pull request naming any operationId that still lacks a FabplaneClient method. If the live document is not deployed yet (404), the job ends without changes.

Local AI, not server AI

fabPlane does not run AI on your photos or files yet: a request with serverAiProcessing: true (--server-ai on the CLI) gets 501 server_ai_unavailable. Let the agent on your machine (Claude Code or Codex through fabplane mcp, or fabdesk) read the part photo or BOM, then call inventory_add or cart_add_items with the fields it extracted.