Init Figma

Init Figma

When to use

When the user is setting up cyber-figma for the first time, or when commands fail with auth, permission, or "team id required" errors.

Ensure cyber-figma CLI

Before running any cyber-figma command, settle how to invoke it — once, in this order. Whichever form resolves is what every cyber-figma <subcommand> in this skill and all other cyber-figma skills means.

1. Shipped CLI (preferred). When these skills came from an installed cyber-figma plugin or npm package, the CLI ships beside them and is bundled with its dependencies inlined, so it needs no install and no network:

   node <cyber-figma-root>/skills/init-figma/scripts/cyber-figma.mjs --version
   

   <cyber-figma-root> is the package root, four levels up from that script; from another cyber-figma skill's own directory the same launcher is ../init-figma/scripts/cyber-figma.mjs. If it prints a version, use it for every later command and skip the rest of this section.

2. Global install — cyber-figma --version. If that succeeds, use the bare cyber-figma spelling.

3. npx fallback — resolve the latest published semver with npm view cyber-figma version and use it as <exact> for every npx cyber-figma@<exact> (never @latest, never a literal placeholder). Check with npx cyber-figma@<exact> --version.

If only the npx path is left and it fails (install prompt, command not found, or other non-zero exit):

1. Tell the user the workflow needs to download cyber-figma from npm (no package.json change).
2. Ask whether to install.
3. After yes, run the one-time install only: npx --yes cyber-figma@<exact> --version
4. For all later commands, use npx cyber-figma@<exact> <subcommand> (no --yes) or cyber-figma if globally installed.
5. If the user declines npx, ask whether to add cyber-figma as a devDependency instead. Note drawbacks: it modifies package.json and may need ignoring in unused-dependency tools (e.g. knip). If they decline both, skip CLI steps.

Global flags and exit codes

Every command inherits these:

Exit codes are stable; branch on them rather than on message text:

For the exact resource commands and their flags, run cyber-figma --help and cyber-figma <resource> --help.

Instructions

1. Check for existing credentials

echo "Token set: ${FIGMA_ACCESS_TOKEN:+yes}${FIGMA_TOKEN:+ (via FIGMA_TOKEN alias)}"
echo "Team set: ${FIGMA_TEAM_ID:+yes}${FIGMA_TEAM:+ (via FIGMA_TEAM alias)}"

FIGMA_TOKEN and FIGMA_TEAM work as aliases, but new setup should use the canonical names. A value that is literally an unexpanded ${VAR} counts as absent — that is what a host config forwards when the variable is not exported, and it is reported as a missing credential rather than sent to Figma.

2. Set FIGMA_ACCESS_TOKEN

If not set, guide the user:

1. Go to Figma → Settings → Security → Generate new token
2. Choose an expiration and select scopes at creation time (see Scopes to pick below)
3. Copy the token — Figma shows it only once
4. Add to the user's shell profile: export FIGMA_ACCESS_TOKEN=... in the file their shell loads on login

Or pass per-command with --token <pat>.

Two facts to tell the user up front, because both look like bugs later:

• A personal access token expires after at most 90 days, and there is no automatic rotation. The old "no expiration" option was removed. Plan on rotating.
• Figma reports an expired token as 403, not 401. If commands that used to work start failing with a permission error, suspect expiry first.

Scopes to pick

A token never exceeds the user's own Figma permissions, so request the narrowest set that covers the intended work. Prefer the granular scopes over the deprecated, extremely permissive files:read.

3. Verify the connection

Ensure the CLI is available first (see Ensure cyber-figma CLI), then run:

cyber-figma user me --toon
# or, if using npx without global install:
npx cyber-figma@<exact> user me --toon

This calls GET /v1/me and prints the authenticated user. (--toon is the token-efficient format; use --json for raw JSON.)

If it fails, the token is invalid, expired, or missing the current_user:read scope.

Plan access tokens cannot call /v1/me at all. If the user is setting up a plan access token (Organization/Enterprise only, minted by an org admin at https://www.figma.com/developers/tokens), verify with a file-metadata read against a known file instead — see step 5.

4. Set FIGMA_TEAM_ID

Figma provides no way to discover a team id from a token — the user must read it from a URL. Ask them to open the team in Figma and copy the segment after /team/:

https://www.figma.com/files/team/1234567890123456789/Some-Team
                                 ^^^^^^^^^^^^^^^^^^^ this

Add it to their shell profile:

export FIGMA_TEAM_ID=<team-id>

This avoids passing --team on every team-scoped command. Verify:

cyber-figma project list --toon

That lists the projects visible to the token holder in that team.

5. Confirm setup

cyber-figma file meta <file-key>

The file key is the segment after /design/ (or the older /file/) in any Figma file URL. A successful metadata read confirms token, scopes, and file access together — and it is the cheapest call in the API (rate-limit tier 3), so it is the safe thing to retry with.

6. Know the limits before the user hits them

Three gates cause almost all confusing failures. Explain whichever applies:

• Seat type, not plan, sets the rate limit. A View or Collab seat gets roughly 6 GET file / GET file nodes / GET image calls per month — on every plan, including Enterprise. If the user's core flow is "read a file", a Dev or Full seat is required for it to be usable at all.
• The limit follows the plan the file lives in, not the best plan the user belongs to. A file sitting in the user's personal (Starter) space gets Starter treatment even for an Enterprise Full-seat user. If a 429 looks wildly out of proportion, check where the file actually lives.
• Six endpoint families are Enterprise-only: Variables (read and write), Library Analytics, Activity Logs, Developer Logs, AI Usage, and Discovery. Activity Logs, Developer Logs, AI Usage, and Discovery additionally require an org admin, and Developer Logs and Discovery additionally require the Governance+ add-on. None of these work with an ordinary PAT on a Starter, Professional, or Organization plan, and Activity Logs, Developer Logs, AI Usage, and Discovery are not reachable with a PAT at all.

On a 429, read the response headers rather than guessing: Retry-After (seconds), X-Figma-Plan-Tier, X-Figma-Rate-Limit-Type (low = View/Collab seat, high = Dev/Full), and X-Figma-Upgrade-Link.

7. Recommended — connect the MCP server (ambient session integration)

For AI agents, prefer connecting the cyber-figma MCP server as an ambient, always-available session integration first — then reach for the on-demand skills as needed. Add the cyber-figma MCP server to your host (see readme — MCP Server) and set CYBER_FIGMA_MCP_FORMAT=toon in its env for token-efficient output.

The plugin ships host configs already, so in most hosts installing the plugin is enough. Those configs pass FIGMA_ACCESS_TOKEN and FIGMA_TEAM_ID through from the environment — the variables still have to be exported in step 2 and step 4.

8. Note — the official Figma MCP server is a different thing

Figma ships its own MCP server, which runs its own OAuth flow and is limited to clients in the Figma MCP Catalog. cyber-figma is not a client of it: it is a REST API wrapper using REST API credentials. The two can coexist under separate config keys.

References

• Figma — personal access tokens
• Figma — scopes
• Figma — rate limits