CLI reference

The CLI is included in @frontfriend/sdk@1.3.0. The executable is named frontfriend; it is not a separate npm package. Examples use pnpm exec frontfriend to run the installed version. With npm, use npx frontfriend after installing the SDK. See Installation.

Connect and verify

pnpm exec frontfriend login
pnpm exec frontfriend connect --ff-id YOUR_DESIGN_SYSTEM_ID --name my-app --framework react --primitive base --tag base --agent codex
pnpm exec frontfriend doctor
pnpm exec frontfriend onboard

connect handles project setup, agent installation, verification and activation. Run it from an application inside a Git work tree. Copy the prompt from Connect in Studio for your agent, or the command under Do it by hand to set the target, tag and adoption levels yourself. setup is the lower-level project configuration command; it does not complete design onboarding.

Use --adopt contracts for design contracts alone, or --adopt contracts,tokens,components for all three. --areas marketing,documentation starts an onboarding run for those project areas. An agent then follows ff-setup, a workspace admin reviews the result, and connect --resume adopts the approved snapshot. --require-ready exits 11 if the application is still waiting; an ordinary successful connection can still be waiting for onboarding.

--dry-run previews connection changes. --json returns structured progress and the next actor. --name identifies the application; use a distinct name for each app. Existing connections retain their identity unless deliberately replaced with --force.

Tokens and diagnostics

pnpm exec frontfriend init
pnpm exec frontfriend init --force
pnpm exec frontfriend init --tag base
pnpm exec frontfriend init --tag base --no-register
pnpm exec frontfriend init --version RELEASE_ID
pnpm exec frontfriend status
pnpm exec frontfriend check --files "src/**/*.{tsx,vue}" --json
pnpm exec frontfriend clean

init prepares the selected tokens and configuration. With a person’s login, it also registers the app on its tag. When the app adopts contracts, init writes them to .frontfriend/design/ and their rules to .frontfriend/rules/. With a machine credential in FF_AUTH_TOKEN, or with --no-register, it installs the selected tag and never registers the app or changes its release tag. See Build in CI and Docker. --version takes an immutable Release ID, not the npm package version. --force refreshes the selection; it does not upgrade installed components. status inspects local configuration and cache state. check checks local files against adopted design rules; use --ci to fail when required verification coverage is incomplete. clean removes the runtime token cache; regenerate it before building.

Download canonical components

pnpm exec frontfriend download button accordion --dry-run
pnpm exec frontfriend download button accordion --yes

The command resolves authenticated source for the selected Release and writes frontfriend.lock.json. Missing npm dependencies are installed with your package manager. all selects the applicable catalogue; review named components first. Set the destination with aliases.ui in Project configuration.

Adopt updates deliberately

pnpm exec frontfriend diff
pnpm exec frontfriend update --dry-run
pnpm exec frontfriend update --yes
pnpm exec frontfriend update button --release RELEASE_ID --dry-run
pnpm exec frontfriend adopt --dry-run

Without a component or selection flag, update adopts what the app’s adoption levels cover: approved design contracts, selected tokens, and installed components with their dependency closure. --installed --tokens selects installed components and tokens explicitly. --contracts-only --working-design adopts approved contracts without changing existing token pins or installing component source.

update installs npm dependencies only for components it adds or moves to another version without a local edit. It adds the packages that package.json lacks and raises a requirement below the minimum of the declared range. It never lowers a newer requirement; it prints a warning instead, such as ⚠️ `lucide-react` stays at 1.17.0; `icon@1.1.0` declares ^0.468.0. Unchanged components impose no dependencies. If an unedited unchanged component declares a package that package.json lacks, update prints the install command without running it. Files that already match the incoming source are reported as unchanged and are not rewritten.

update --json prints one JSON result on stdout and needs --yes or --dry-run. npm_dependencies lists the install requests (missing, command), the newer requirements kept (kept) and the packages unchanged components lack (repair). files_unchanged counts the identical files and files_kept lists kept local edits. Its components_removed lists pins of private components deleted from the Design System. update removes those pins from frontfriend.lock.json and keeps their files. See Private components. A contract deleted from the Design System leaves the lock too: update removes its file from .frontfriend/design/ and its rules from .frontfriend/rules/.

adopt adopts the latest published Release of the app’s tag. A component or foundation commit publishes a new revision on base; apps adopt it separately through their lockfile, and other tags move only by promotion or rollback. Use --replace only after reviewing files owned by another component or unmanaged local source. A changed tag does not silently overwrite an application’s installed source.

Private components

pnpm exec frontfriend add custom/acme/data-grid --dry-run
pnpm exec frontfriend add custom/acme/data-grid --yes
pnpm exec frontfriend publish --manifest ./frontfriend-component.json

add requires an explicit custom/... address. publish writes an immutable private version to the connected Design System. It needs publication permission and a valid manifest. See Private components. The old page/project add operations are not part of the SDK.

Native shadcn and migration

pnpm exec frontfriend import-shadcn --help
pnpm exec frontfriend migrate --help
pnpm exec frontfriend restore
pnpm exec frontfriend eject --dry-run

A Design System with the shadcn base can keep native tokens and source. Its first app performs the initial import; later apps consume that published system. migrate converts to the Frontfriend base and writes to the platform. restore without an ID lists recovery snapshots; inspect the chosen snapshot before restoring. eject requires a supported plan and an online connection. Read Adopt Frontfriend and Code ownership before running these writes.

Agents and design context

pnpm exec frontfriend agents install --client codex
pnpm exec frontfriend agents configure
pnpm exec frontfriend mcp doctor
pnpm exec frontfriend design context
pnpm exec frontfriend design validate
pnpm exec frontfriend design sync
pnpm exec frontfriend logout

Agent installation configures the user-level MCP bridge and skills. agents configure refreshes project integration. design sync refreshes generated context; it does not approve or adopt a new design. Restart the coding agent after installing its bridge. See MCP and Design Skills.

Help and errors

Run pnpm exec frontfriend --help and pnpm exec frontfriend COMMAND --help for the installed version. Commands that consume a Design System require an ff-id; they stop before writing when it is absent. An unknown Design System, a workspace access denial, and a plan restriction are different errors. See Troubleshooting.