CLI Reference

handoff-appis the workspace CLI. Install it globally and run all commands from your workspace's handoff/ directory.

Installation

npm install -g handoff-app

Or install as a dev dependency and run via npx handoff-app <cmd>.

Authentication

handoff-app login --url https://your-registry.vercel.app

Opens a browser device-code flow. After approving, credentials are saved to .handoff/cli-auth.json. All subsequent push/pull commands use this token automatically.

Authorize CLI device

Commands

handoff-app login

Authenticate with a registry via browser OAuth device flow. Saves credentials to .handoff/cli-auth.json.

--url <url>Registry URL (e.g. https://your-registry.vercel.app)

handoff-app push:all

Push all workspace data to the registry in sequence: config, theme, navigation, pages, tokens, DTCG tokens, icons, logos.

handoff-app push

Push individual components, patterns, and pages via POST /api/sync/upload. Skips unchanged files.

handoff-app pull

Pull changeset from the registry and write back to the workspace — pages, component declarations, build artifacts, source files.

handoff-app fetch

Pull design tokens from Figma into public/api/tokens/. Requires FIGMA_PROJECT_ID and FIGMA_DEVELOPER_ACCESS_TOKEN.

handoff-app dev

Run a local filesystem-backed preview of the design system site (workspace dev mode — no database required).

handoff-app build

Build a component's Vite bundle locally and write artifacts to components/[id]/dist/.

<componentId>Component identifier

handoff-app init:vercel

Scaffold a vercel.json and .env.example for deploying this app as a registry on Vercel.

push:all — step by step

Endpoint	Source
POST /api/registry/config	handoff.config.js app block
POST /api/registry/theme	theme.css
POST /api/registry/navigation	pages/ directory tree
POST /api/registry/pages	pages/*/.md
POST /api/registry/tokens	public/api/tokens.json
POST /api/registry/dtcg	design-system/manifest.json + dist/
POST /api/registry/icons	icons/catalog.json (flat IconCatalogEntry[])
POST /api/registry/logos	logos/logo-set.json (LogoSet object)

Environment variables

Variable	Purpose
HANDOFF_CLOUD_URL	Registry base URL (e.g. https://handlebars-registry.example)
HANDOFF_CLOUD_TOKEN	Bearer token — only needed for CI; prefer handoff-app login for local dev
FIGMA_PROJECT_ID	Figma file key for handoff-app fetch
FIGMA_DEVELOPER_ACCESS_TOKEN	Figma personal access token for handoff-app fetch
DATABASE_URL	Postgres connection string (registry server only — not needed in workspaces)