Skip to content

For AI agents

This documentation is also published as Markdown for LLMs, generated from these pages on every deploy:

This repository and the npm package ship agent-friendly docs:

For scripted/agent usage prefer --stdout --quiet (pure JSON on stdout, logs on stderr) and pass tokens via environment variables. Run it as npx tokens-bruecke@latest so the agent always gets the newest release: plain npx tokens-bruecke can reuse an old cached copy. See Update notice.

If your agent can run code inside Figma — a Figma agent, an MCP server with evaluate_script, or your own plugin — it already has Plugin API access to the open file. In that case it should not go through the REST API at all:

REST API (--file-key)Snapshot (--input)
Figma Enterprise planRequiredNot required
Personal access / OAuth tokenRequiredNot required
File must be published / shared with the tokenYesNo — works on whatever file is open
Network calls to FigmaSeveral per exportNone

The agent’s job is only to dump data; the CLI still owns every transform, so aliases, modes, scopes and DTCG formatting behave exactly as they do in REST mode.

1. Extract the snapshot from inside Figma. Plugin API objects are live proxies, so JSON.stringify on them may serialize as empty — copy the fields onto plain objects first:

const snapshot = {
variableCollections: (
await figma.variables.getLocalVariableCollectionsAsync()
).map((c) => ({
id: c.id,
name: c.name,
defaultModeId: c.defaultModeId,
modes: c.modes.map((m) => ({
modeId: m.modeId,
name: m.name,
parentModeId: m.parentModeId,
})),
variableIds: c.variableIds,
// Extended collections only (undefined otherwise)
isExtension: c.isExtension,
parentVariableCollectionId: c.parentVariableCollectionId,
rootVariableCollectionId: c.rootVariableCollectionId,
variableOverrides: c.variableOverrides,
})),
variables: (await figma.variables.getLocalVariablesAsync()).map((v) => ({
id: v.id,
name: v.name,
variableCollectionId: v.variableCollectionId,
resolvedType: v.resolvedType,
description: v.description,
scopes: v.scopes,
codeSyntax: v.codeSyntax,
valuesByMode: v.valuesByMode,
})),
// Optional — only needed if the config enables the matching style type
paintStyles: (await figma.getLocalPaintStylesAsync()).map((s) => ({
id: s.id,
name: s.name,
description: s.description,
paints: s.paints,
boundVariables: s.boundVariables,
})),
};
const json = JSON.stringify(snapshot, null, 2);

Text, effect and grid styles follow the same pattern — see schemas/tokens-snapshot.schema.json for the fields each one needs.

2. Pipe it through the CLI.

Terminal window
# From a file the agent wrote
npx tokens-bruecke@latest --input snapshot.json --output tokens.json
# Or straight from stdin, no temp file
my-figma-agent dump-tokens | npx tokens-bruecke@latest --input - --stdout --quiet > tokens.json
# All the usual options still apply
npx tokens-bruecke@latest --input snapshot.json --config config.json --split-by-mode --output ./tokens

Snapshot mode ignores FIGMA_API_KEY / FIGMA_FILE_KEY, so a token exported in the environment won’t get in the way. Passing --api-key, --oauth-token or --file-key explicitly alongside --input is rejected as a conflict.

On a bad snapshot the CLI exits 1 and names the offending key — for example variables[3] is missing a string "variableCollectionId" — so an agent can correct its dump and retry without guesswork.