CLI reference

The Code Connect CLI (@figma/code-connect) is a command-line interface for publishing and managing Code Connect connections from your terminal or CI/CD pipelines.

Usage

npx figma connect [command] [options]

Commands

Command	Description
`npx figma connect publish`	Publish Code Connect files to Figma
`npx figma connect unpublish`	Remove published Code Connect connections
`npx figma connect parse`	Parse Code Connect files and output as JSON
`npx figma connect create`	Generate a boilerplate Code Connect template file
`npx figma connect migrate`	Migrate parser-based Code Connect files to template files
`npx figma connect preview`	Preview how Code Connect snippets will render in the Figma inspect panel

Global options

Option	Description
`-a, --api-url <url>`	Custom Figma API URL to use instead of `https://api.figma.com/v1`. Overrides `apiUrl` in `figma.config.json`.
`-V, --version`	Output the version number
`-v, --verbose`	Enable verbose logging for debugging
`-t, --token <token>`	Figma access token to use. Falls back to the `FIGMA_ACCESS_TOKEN` environment variable if omitted.
`-h, --help`	Display help for command

figma connect publish

Scan for Code Connect files and publish them to Figma.

Usage

npx figma connect publish [options]

Options

Option	Description
`-r, --dir <dir>`	Directory containing your Code Connect project (defaults to cwd)
`-f, --file <file>`	Path to a single Code Connect file to publish
`-c, --config <path>`	Path to a figma config file
`--exit-on-unreadable-files`	Exit if any Code Connect files cannot be parsed. Recommended for CI/CD.
`--dry-run`	Test publishing without actually publishing
`--skip-validation`	Skip validation of Code Connect docs
`-l, --label <label>`	Label to apply to the published files
`-b, --batch-size <batch_size>`	Batch size (number of documents) to use when uploading
`--force`	Overwrite existing UI-created Code Connect mappings if they conflict with the files being published
`-h, --help`	Display help for command

Description

Finds Code Connect files in the specified directory, validates them against the Figma API, and publishes them. Published connections appear in Dev Mode for the linked Figma components.

Examples

Publish all Code Connect files in the current directory:

npx figma connect publish

Publish from a specific directory:

npx figma connect publish --dir src/components

Publish a single file:

npx figma connect publish --file src/components/Button.figma.ts

Dry run to see what would be published:

npx figma connect publish --dry-run

Publish with a label:

npx figma connect publish --label "React"

Force-overwrite UI-created mappings:

npx figma connect publish --force

figma connect unpublish

Remove published Code Connect connections from Figma.

Usage

npx figma connect unpublish [options]

Options

Option	Description
`-r, --dir <dir>`	Directory containing your Code Connect project (defaults to cwd)
`-f, --file <file>`	Path to a single Code Connect file to unpublish
`-c, --config <path>`	Path to a figma config file
`--exit-on-unreadable-files`	Exit if any Code Connect files cannot be parsed. Recommended for CI/CD.
`--dry-run`	Test unpublishing without actually unpublishing
`--node <link_to_node>`	Specify the Figma node to unpublish
`-l, --label <label>`	Label to unpublish for
`-h, --help`	Display help for command

Description

Scans for Code Connect files and removes their published connections from Figma. You can unpublish all connections found in a directory, or target a specific node and label combination.

When using --node, the --label option is required.

Examples

Unpublish all Code Connect files in the current directory:

npx figma connect unpublish

Unpublish connections from a specific directory:

npx figma connect unpublish --dir src/components

Unpublish a specific node by URL:

npx figma connect unpublish --node "https://figma.com/file/abc123/..." --label "React"

Dry run to preview what would be unpublished:

npx figma connect unpublish --dry-run

figma connect parse

Parse Code Connect files and output them as JSON.

Usage

npx figma connect parse [options]

Options

Option	Description
`-r, --dir <dir>`	Directory containing your Code Connect project (defaults to cwd)
`-f, --file <file>`	Path to a single Code Connect file to process
`--outFile <file>`	Specify a file to write the JSON output to
`-c, --config <path>`	Path to a figma config file
`--exit-on-unreadable-files`	Exit if any Code Connect files cannot be parsed. Recommended for CI/CD.
`--dry-run`	Test parsing without producing output
`-l, --label <label>`	Label to apply to the parsed files
`-h, --help`	Display help for command

Description

Finds Code Connect files in the specified directory, parses them into their JSON representation, and outputs the result. By default, the JSON is written to stdout. Use --outFile to write it to a file instead.

This is useful for debugging your Code Connect setup or integrating with other tools.

Examples

Parse all Code Connect files and print JSON to stdout:

npx figma connect parse

Parse and write to a file:

npx figma connect parse --outFile output.json

Parse a single file:

npx figma connect parse --file src/components/Button.figma.ts

Parse with a label:

npx figma connect parse --label "React"

figma connect create

Generate a boilerplate Code Connect template file for a Figma component, populated with the property values ready to be used in code. Example output:

// url=https://www.figma.com/file/1234abcd/My-File?node-id=123
import figma from "figma"

/**
 * NEXT STEPS:
 * - Replace the `example` with the actual code snippet you want to show
 *   (e.g. figma.code`<Button label="${propertyValue}" />`)
 * - Update the `imports` array with any lines of code that should be displayed
 *   at the top (e.g. imports: ['import { Button } from "./Button"'])
 */

const label = figma.selectedInstance.getString("Label")
const hasIcon = figma.selectedInstance.getBoolean("Has Icon")

export default {
  example: figma.code``,
  imports: [],
  id: "Button",
  metadata: {
    nestable: true,
  },
}

Usage

npx figma connect create <figma-node-url> [options]

Arguments

Argument	Description
`<figma-node-url>`	The URL of the Figma component node to generate a Code Connect file for

Options

Option	Description
`--outDir <dir>`	Specify a directory to output generated Code Connect template
`-c, --config <path>`	Path to a figma config file
`-h, --help`	Display help for command

Description

Fetches component information from the Figma API for the given node URL and generates a boilerplate .figma.ts Code Connect file in the current directory (or --outDir if specified). The generated file includes:

Property accessor declarations for each component property (e.g. getBoolean, getString, getEnum)
An export default object with placeholder example, imports, and id fields
Inline comments with next steps for completing the template

The file is named after the component (e.g. MyComponent.figma.ts). If the file already exists, the command exits with an error.

Examples

Generate a Code Connect file for a component:

npx figma connect create "https://www.figma.com/file/1234abcd/Test-File?node-id=1-39"

Generate into a specific output directory:

npx figma connect create "https://www.figma.com/file/1234abcd/Test-File?node-id=1-39" --outDir src/components

figma connect preview

Preview how Code Connect snippets will render in the Figma inspect panel without publishing them.

Usage

npx figma connect preview [files...] [options]

Arguments

Argument	Description
`[files...]`	Code Connect files to preview (e.g. `Button.figma.tsx`). Leave empty to preview all files.

Options

Option	Description
`-r, --dir <dir>`	Directory containing your Code Connect project (defaults to cwd)
`-c, --config <path>`	Path to a figma config file
`--output <format>`	Output format: `table` (default) or `json`
`--inspect`	List the component's properties and variants, including options and defaults, without rendering
`--props <pairs...>`	Render one property combination; unspecified properties use their defaults
`--all`	Render every combination of the component's boolean and variant properties; requires a specific component file
`--unique`	Similar to `--all` but hides any results with duplicated output
`--max-combinations <number>`	Limit the combinations rendered by `--all` or `--unique` (default and maximum: 500)
`-h, --help`	Display help for command

Description

Parses the given Code Connect files (or every Code Connect file in the directory, if no files are specified), renders each snippet as it would appear in Dev Mode, and reports the result. For snippets written in Prettier-supported languages (e.g. TypeScript, JavaScript, JSX/TSX), the rendered output is also validated with Prettier to surface syntax errors before they ship; snippets in other languages are returned as-is.

Use this to iterate on a template locally: tweak your .figma.ts or template file, run npx figma connect preview, and see exactly what Figma would show without having to publish.

To preview different component states, use --inspect to see the available properties and variants, --props to render one combination, or --all to render every boolean and variant combination. Property names and variant values passed to --props are case-insensitive.

Some components have properties that don't affect the rendered snippet, so --all prints the same code many times over. --unique renders the same set of combinations but reports each distinct snippet once, annotated with how many combinations produced it

Examples

Preview every Code Connect file in the current directory:

npx figma connect preview

Preview a specific file:

npx figma connect preview src/components/Button.figma.ts

Inspect and preview different states of a component:

npx figma connect preview src/components/Button.figma.ts --inspect
npx figma connect preview src/components/Button.figma.ts --props Variant=Primary "Has Icon Start=true"
npx figma connect preview src/components/Button.figma.ts --all --max-combinations 20
npx figma connect preview src/components/Button.figma.ts --unique

Preview multiple files:

npx figma connect preview src/components/Button.figma.ts src/components/Input.figma.ts

Output as JSON (useful for piping into other tools):

npx figma connect preview --output json

figma connect migrate

Migrate existing parser-based Code Connect files into template files.

Usage

npx figma connect migrate [options]

Options

Option	Description
`-r, --dir <dir>`	Directory containing your Code Connect project (defaults to cwd)
`-f, --file <file...>`	One or more Code Connect files to migrate. If omitted, all files in project are migrated.
`--outDir <dir>`	Write migrated template files to a specific directory instead of alongside the source files
`-c, --config <path>`	Path to a figma config file
`--javascript`	Output `.figma.js` files instead of the default `.figma.ts` files
`--delete`	Delete source Code Connect files after they are successfully migrated
`--batch <mode>`	Batch migration mode: `auto`, `all`, or `none`. Defaults to `auto`, which attempts files with 10 or more Code Connect connections.
`--include-props`	Preserve `__props` metadata blocks in the migrated output. Pass this flag if using the React `.getProps()` or `.render()` modifiers, or if other template files read `executeTemplate().metadata.__props` from the migrated components.
`-h, --help`	Display help for command

Description

By default, the migration command scans the current Code Connect project using your figma.config.json include/exclude settings and writes .figma.ts template files.

Use --file to migrate one or more exact files from the selected project. To migrate a folder or subtree, limit include/exclude in figma.config.json.

Files with 10 or more Code Connect connections are automatically considered for batch-file output. If batching is not safe, the command falls back to regular template files. Use --batch all to attempt batching every selected source file, or --batch none to always write regular template files.

For a full walkthrough of running the migration, reviewing the output, and testing the results in Figma, see the migration guide.

Examples

Migrate the current Code Connect project to a specified location:

npx figma connect migrate --outDir src/migrated

Migrate specific files:

npx figma connect migrate --file src/components/Button.figma.tsx src/components/Input.figma.tsx

Force a specific file to batch if possible:

npx figma connect migrate --file src/icons.figmadoc.tsx --batch all

Usage​

Commands​

Global options​

figma connect publish​

Usage​

Options​

Description​

Examples​

figma connect unpublish​

Usage​

Options​

Description​

Examples​

figma connect parse​

Usage​

Options​

Description​

Examples​

figma connect create​

Usage​

Arguments​

Options​

Description​

Examples​

figma connect preview​

Usage​

Arguments​

Options​

Description​

Examples​

figma connect migrate​

Usage​

Options​

Description​

Examples​

Usage

Commands

Global options

figma connect publish

Usage

Options

Description

Examples

figma connect unpublish

Usage

Options

Description

Examples

figma connect parse

Usage

Options

Description

Examples

figma connect create

Usage

Arguments

Options

Description

Examples

figma connect preview

Usage

Arguments

Options

Description

Examples

figma connect migrate

Usage

Options

Description

Examples