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:
| Variable | Meaning |
|---|---|
FABPLANE_TOKEN | An fpk_… API token, fpd_… device token, or fpb_… bot token |
FABPLANE_API_ORIGIN | API server, default https://api.fabplane.com |
FABPLANE_ORG | Default organization id or slug for commands and MCP tools |
FABPLANE_CREDENTIALS_FILE | Override 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.
| Command | What 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 whoami | Show 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 list | List 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 joinable | Orgs you can join via your verified email domain. |
fabplane orgs join <id> | Join an org through its email-domain join. |
fabplane tokens list | List 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 status | Is the fabPlane desktop app running? (reads daemon.json) |
fabplane desktop projects | List fabdesk projects. |
fabplane desktop tools | List 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 version | Print 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.