figura-cli

Command-line client for the Figura visualization SaaS. Talks to the Figura /api/v1 HTTP API with a Bearer fig_ token.

Install

# global (preferred)
bun add -g figura-cli
# or run ad-hoc
bunx figura-cli --help

# no bun? npm/npx still work:
npm i -g figura-cli
npx figura-cli --help

The binary is figura.

Update later with one command — it bumps the CLI (and the bundled figura mcp server) to the latest and reinstalls the skills to match:

figura update            # detects bun vs npm; add --dry-run to preview

Authentication

# browser login (default) — opens a short authorize page, no token to paste
figura login

# print the URL instead of opening a browser (still no paste)
figura login --no-browser

# or pass a token directly (CI / headless)
figura login --token fig_xxxxxxxxxxxx

figura login uses an OAuth-2.0 device flow: the CLI gets a device code from the engine, opens a clean authorize URL (no localhost port), and polls until you approve in the browser — nothing to copy-paste, and it works over SSH. The minted fig_ token is validated against GET /v1/whoami, then written to ~/.figura/config.json (mode 0600) with { apiUrl, token, team }.

Resolution precedence:

| Value | Order | | ------ | ------------------------------------------------------ | | token | FIGURA_TOKEN env → --token flag → project .figura/config.json → global ~/.figura/config.json | | apiUrl | FIGURA_API_URL env → --api-url flag → project config → global config → default https://figura.so |

Multiple teams — one per project

A project config (.figura/config.json, found by walking up from the current directory) overrides the global one, so each repo can use its own team — with its own brand and company brain:

cd ~/workspace/pano-fm && figura login --project   # pin this repo to Pano's team
cd ~/workspace/sha7n   && figura login --project   # pin this repo to sha7n's team

Now every figura/fig/brand command (and figura mcp — so Claude Code too) resolves the team from the nearest .figura/config.json. The file holds a live token, so add .figura/ to the repo's .gitignore.

Brand — set it from your repo, no UI

Figs render against your team's brand profile. Set it from the CLI instead of the figura.so UI:

# pipe a tokens block (colors+roles, type, spacing, voice) — exactly what /fig reads
cat tokens.txt | figura brand set --name "Acme" --description "a SaaS analytics dashboard" --tokens -
figura brand                       # verify (shows name / product / token size)

Omitted fields keep their saved value — a name-only brand set won't wipe your tokens. Best of all, let Claude Code build the whole profile from your codebase — see the figura-brand skill below ("introduce my repo to Figura").

Claude Code skills

Install the bundled skills so Claude Code can work with Figura from any project:

figura skill install            # → ~/.claude/skills (global)
figura skill install --project  # → ./.claude/skills (this repo only)

This installs both:

• /fig — generate on-brand, device-framed HTML figs in your team (thin wrapper over the Figura MCP).
• figura-brand — "introduce my repo to Figura": Claude scans the repo's design system (tokens, brand docs, app name) and sets your team's brand profile for you.

Re-run after upgrading figura-cli to update them — the skills are bundled with the CLI, so they stay in lockstep.

MCP server

The Figura MCP server ships inside the CLI — no separate install. Add it to Claude Code with:

claude mcp add figura -- figura mcp

figura mcp serves the same tools as the standalone figura-mcp package, but resolves your token from the nearest .figura/config.json (see Multiple teams above), so the MCP uses the right team per project automatically. (The bunx -y figura-mcp form still works if you'd rather not install the CLI.)

Usage

figura whoami                       # show the authenticated identity
figura teams                        # list accessible teams

# Create a fig from a file or stdin
figura fig create --file mock.html --title "Feed redesign" --area feed --tags ui,feed
cat mock.html | figura fig create --area profile --orientation landscape

# List + inspect
figura fig list --area feed --tag ui --limit 20
figura fig list --json
figura fig get <id>

# Open in the browser (downloads the raw HTML to a temp file)
figura fig open <id>
figura fig open <id> --print        # write HTML to stdout instead

# Comment
figura comment <id> --body "ship it"

# Token introspection
figura token current

Every command accepts --help. Add --json where noted to get machine-readable output.

Global options

• --token <fig_...> — override the token for one invocation
• --api-url <url> — override the API base
• --help, -h — help
• --version, -v — version

Development

bun install
bun run dev -- --help   # run from source with bun
bun run build           # bundle + minify src -> dist/index.js (single file)
node dist/index.js --help