CLI Reference

Master the Handoff CLI with this full reference of every command, flag, and configuration option available to your team. Whether you are scaffolding new components, building documentation, or ejecting configurations for customization, this guide has the technical details you need. Empower your local environment with the full power of the Handoff engine.

This is the complete technical reference for the handoff-app command-line interface. If you are just getting started, we recommend following the CLI Quickstart first.

Core Commands

Command	Description
`handoff-app init`	Create a new Handoff project interactively.
`handoff-app fetch`	Pull design decisions and metadata from Figma.
`handoff-app start`	Launch the local documentation development server.
`handoff-app build:app`	Compile your documentation site for production.
`handoff-app scaffold`	Generate component implementations from Figma tokens.

Configuration Ejection

Handoff allows you to "eject" its default configurations and templates into your local project so you can customize them to your heart's content.

Command	Description
`handoff-app eject:config`	Eject `handoff.config.js` to your project root.
`handoff-app eject:integration`	Eject integration templates for custom styling.
`handoff-app eject:pages`	Eject default documentation pages for custom content.

Global Options

The following flags can be used with any Handoff command to modify its behavior.

Flag	Description
`-c, --config [file]`	Path to a custom Handoff configuration file.
`-d, --debug`	Enable verbose debug logging for troubleshooting.
`-v, --version`	Display the current version of the CLI.

Environment Variables

You can also configure Handoff using environment variables. This is particularly useful for managing credentials like HANDOFF_FIGMA_PROJECT_ID and HANDOFF_DEV_ACCESS_TOKEN in CI/CD environments.

Command reference

The sections below expand on the summary tables and include every command exposed by current handoff-app releases. Run handoff-app <command> --help for the exact options shipped with your installed version.

Most commands accept -c, --config (path to config file), -f, --force, and -d, --debug where listed below. init is an exception (see its section). --help and --version are available on every command.

`handoff-app init`

Description: Initialize a new Handoff project using an interactive wizard (project layout, configuration, and dependencies).

Usage:

example.sh
bash
1handoff-app init

Options: --help, --version only (no -c / -f / -d on this command in the default CLI).

`handoff-app fetch`

Description: Connect to Figma using your configuration and download design tokens, components, and related metadata into the project.

Usage:

example.sh
bash
1handoff-app fetch

Options:

Option	Description
`-c, --config <file>`	Path to a Handoff config file.
`-f, --force`	Force the action when the CLI would otherwise skip or prompt.
`-d, --debug`	Verbose logging for troubleshooting.
`--help`	Show help.
`--version`	Show CLI version.

`handoff-app start`

Description: Start the design system documentation app in development mode (local preview server).

Usage:

example.sh
bash
1handoff-app start

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app dev`

Description: Same purpose as start in the default CLI—run the design system in development mode. Prefer whichever command your project’s package.json scripts use.

Usage:

example.sh
bash
1handoff-app dev

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app build:app`

Description: Produce a production build of the documentation application.

Usage:

example.sh
bash
1handoff-app build:app

Options:

Option	Description
`-c, --config <file>`	Path to config file.
`-f, --force`	Force action.
`-d, --debug`	Debug logging.
`--skip-components`	Skip building components before building the app (default: `false`).
`--help`, `--version`	Standard.

`handoff-app build:components`

Description: Build all project components, or build a single component by name.

Usage:

example.sh
bash
1handoff-app build:components
2handoff-app build:components <component>

Arguments:

Argument	Description
`component`	Optional. When provided, only that component is built.

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app scaffold`

Description: Generate component stubs in your project for components that have been fetched from Figma, so you can implement or extend them locally.

Usage:

example.sh
bash
1handoff-app scaffold

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app validate:components`

Description: Validate components in the design system (structure, build, or project rules as implemented by your CLI version).

Usage:

example.sh
bash
1handoff-app validate:components

Options:

Option	Description
`-c, --config`, `-f, --force`, `-d, --debug`	Same as other commands.
`--skip-build`	Skip the build step before validation (default: `false`).
`--help`, `--version`	Standard.

`handoff-app make:page`

Description: Create a new documentation page in the project.

Usage:

example.sh
bash
1handoff-app make:page <name> [parent]

Arguments:

Argument	Description
`name`	Required. Page name (and typically route slug).
`parent`	Optional. Parent route or grouping when your CLI supports nested pages.

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app make:component`

Description: Create a new HTML-oriented code component you can embed in documentation content.

Usage:

example.sh
bash
1handoff-app make:component <name>

Arguments:

Argument	Description
`name`	Required. Name for the new component.

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app make:template`

Description: Create a new template for a component (for example a specific variant or state).

Usage:

example.sh
bash
1handoff-app make:template <component> [state]

Arguments:

Argument	Description
`component`	Required. Target component.
`state`	Optional. State or variant identifier.

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app eject:config`

Description: Copy Handoff’s default configuration into the current working directory (typically handoff.config.js) so you can customize behavior.

Usage:

example.sh
bash
1handoff-app eject:config

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app eject:integration`

Description: Eject integration templates for custom styling and deeper control over how Handoff renders and connects to your stack.

Usage:

example.sh
bash
1handoff-app eject:integration

Options: Shared flags (-c, -f, -d, --help, --version) apply when the command is present in your installed CLI. Run handoff-app eject:integration --help to confirm. Some releases expose theme customization via eject:theme (see below) instead—check handoff-app --help for the full command list.

`handoff-app eject:pages`

Description: Eject default documentation pages into the project so you can edit markdown and structure locally.

Usage:

example.sh
bash
1handoff-app eject:pages

Options: -c, --config, -f, --force, -d, --debug, --help, --version.

`handoff-app eject:theme`

Description: Eject the currently selected theme’s files so you can customize styling and assets.

Usage:

example.sh
bash
1handoff-app eject:theme

Options: -c, --config, -f, --force, -d, --debug, --help, --version.