CLI

The binary is handoff-app. In a project that init created, run it through the npm scripts so local development and CI use the project's version, and pass options after --:

Terminal

npm run build -- --target registry
npx handoff-app validate:components
npx handoff-app publish --help

Every command runs against the working directory: the current directory, or HANDOFF_WORKING_PATH.

Shared options

Every command except init accepts:

Option	Effect
`-c, --config <file>`	Load this config file, relative to the working directory, instead of `handoff.config.*`
`--profile <name>`	Merge `handoff.config.<name>.*` onto the base config, and use that profile's registry login. Wins over `HANDOFF_PROFILE`.
`-d, --debug`	Show debug logs
`-f, --force`	Force the action. The effect depends on the command.
`--help`	Show the command's help

handoff-app --version prints the CLI version.

Project

Command	Does
`init`	Creates a project with an interactive wizard, installs `handoff-app`, and adds npm scripts
`fetch`	Fetches tokens and assets from Figma into `exported/`. See Figma foundations.
`start`	Starts the workspace server with the Handoff file watchers
`dev`	Starts the workspace server without the file watchers
`build`	Builds a static site or a registry. See below.
`build:app [--skip-components]`	Builds the static site. Same as `build --target static`.
`build:components [component]`	Builds catalog items without the app. A name builds one item.
`validate:components [--skip-build]`	Builds the catalog in validation mode and runs the `validateComponent` hook. `--skip-build` skips the build step.

build

Terminal

handoff-app build [--target static|registry] [--package standalone|vercel] [--skip-components]

Option	Effect
`--target static`	Default. Static site in `out/static`.
`--target registry`	Standalone registry server in `out/registry`, always in registry mode
`--package vercel`	Vercel Build Output bundle in `.vercel/output` for the selected target
`--package standalone`	The default output of the target
`--skip-components`	Builds the app without a component build first
`-f, --force`	Rebuilds every component, ignoring the build cache

Content

Command	Does
`make:component <name>`	Creates a Handlebars catalog item (template, CommonJS declaration, optional JS and Sass) in the first `catalog.include` directory, or `components/`, and registers that directory. `--force` overwrites the template.
`make:page <name> [parent]`	Creates `pages/<name>.md` or `pages/<parent>/<name>.md`, starting from a default page with the same name when one exists. `--force` overwrites.
`scaffold`	Creates catalog item stubs for the components in the fetched Figma data
`eject:config`	Writes the default config to the working directory. Asks for TypeScript or JavaScript. `--force` overwrites.
`eject:pages`	Copies the default pages to `pages/`. `--force` adds the defaults you have not changed.
`eject:theme`	Copies the selected theme to `theme/default.scss`

Registry

Command	Does
`db:migrate`	Applies the registry database migrations, with the configured driver. Run before the first deployment and before each upgrade.
`login [--url <url>] [--no-browser]`	Authorizes the CLI through the registry's device flow and saves the login under the selected profile
`logout [--url <url>] [--all]`	Revokes and removes the selected profile's login. `--url` limits it to that registry; `--all` removes every login.
`publish <catalog\|pages\|tokens\|assets\|all> [id...]`	Builds and publishes to the connected registry. `--dry-run` lists the upload; `--no-build` uses the existing output.
`checkout <catalog\|pages\|tokens\|assets\|all> [id...]`	Writes registry content into the workspace. `--dry-run` lists the files.

See Connect a workspace for how publish and checkout pick a credential, and Publish and checkout for the details.

Deprecated

These still run, with a deprecation warning.

Command	Use instead
`push [type] [id...]`	`publish`
`push:all`	`publish all`
`push:tokens [setId...]`	`publish tokens`
`push:assets [collection]`	`publish assets`
`pull [type] [id...]`	`checkout`

Logging

HANDOFF_LOG_LEVEL (debug, info, warn, error, silent) and HANDOFF_LOG_SCOPES (handoff, vite, next) control the output of every command. See Environment.