CLI reference

Run with npx brandrail, or install it: npm i -D brandrail. Node 18.18 or later.

connect

brandrail connect

Sign in through the browser and set the project up: Brand Kit, AI rule files, MCP server for Claude Code, Cursor and Copilot, and the UI kit.

`--no-browser`	Print the approval link instead of opening it
`--no-install`	Don't add @brandrail/kit to package.json
`--remote`	Point AI tools at the hosted MCP server instead of the local one
`--framework <name>`	react \| angular \| vue \| web-components \| html (default: from package.json)
`--tokens-css <file>`	Where to write the CSS variables (default src/brandrail.tokens.css)
`--no-rules`	Don't write the AI rule files

check

brandrail check [paths...]

Scan files and print violations with a brand score.

`--config <file>`	Config file (default: nearest brandrail.config.json)
`--format <fmt>`	pretty \| json \| markdown \| github (default: pretty)
`--fail-below <score>`	Exit 1 when the brand score is lower
`--changed [base]`	Only report lines changed vs the base branch (default: origin/main)
`--staged`	Only the lines staged for the next commit (what the pre-commit hook runs)
`--strict`	Exit 1 on any error; warnings never fail
`--upload`	Send the result to the dashboard (scores and messages, never code)
`--no-color`	Plain output

hook

brandrail hook install | brandrail hook uninstall

Add a git pre-commit hook that checks the staged lines on each commit: errors stop the commit, warnings don't. Works with Husky and existing hooks; skip once with git commit --no-verify.

--fail-below <score> Also stop the commit when the staged lines score lower

scan

brandrail scan <url>

Check a running page (localhost, staging, behind a login) in a real browser. Needs Playwright: npm i -D playwright && npx playwright install chromium.

`--pages <n>`	Also scan pages it links to, up to n in total (default 1, max 20)
`--storage-state <file>`	Playwright storage state with your login cookies
`--wait <ms>`	Extra wait after load, for client-rendered apps
`--width <px>`	Viewport width (default 1280)
`--format, --fail-below, --upload`	As for check

migrate

brandrail migrate [paths...]

What's left on the way to the design system, per library and per file.

`--json`	Machine-readable output
`--top <n>`	How many files to list (default 15)
`--upload`	Store the result in the dashboard (scores and counts, never code)

report

brandrail report

Write a shareable HTML handover report: paths and counts, no code.

--out <file> Where to write it (default brandrail-report.html)

mcp

brandrail mcp

Run the MCP server on this machine. AI tools start it; code never leaves the machine.

`--framework <name>`	Override the detected framework
`--report`	Also send brand scores (never code) to the dashboard

init

brandrail init

Create brandrail.config.json and the AI rule files without signing in (starter tokens), or from your published kit.

`--from-api`	Pull the published Brand Kit (needs connect or BRANDRAIL_KEY)
`--mcp`	Also add the MCP server to .mcp.json, .cursor/mcp.json, .vscode/mcp.json and print the Codex / Windsurf config
`--force`	Overwrite an existing brandrail.config.json
`--framework, --tokens-css, --no-rules`	As for connect

import

brandrail import <files...>

Load tokens into the config: DTCG, Tokens Studio, Figma variables JSON, or Figma's Export modes ZIP.

`--replace`	Replace the config's tokens instead of merging
`--primitives`	Keep raw palette ramps (gray.100…900) that semantic tokens point at

export

brandrail export <formats...>

Writes the Brand Kit for other platforms: ios (SwiftUI), compose (Jetpack Compose), android-xml, react-native, flutter, css, tailwind or json. Light and dark colours, spacing, radius and the type scale. Run it in a mobile app's CI to stay current.

`--out <folder>`	Where to write (with several formats, a folder each)
`--from-api`	Use the published Brand Kit (respects brandKitVersion) instead of brandrail.config.json

template

brandrail template [name]

Writes a starting page built from your components: list, detail, form, settings, dashboard or sign-in, in your project's framework. Without a name, lists them. Parts your registry has no component for get a comment saying what goes there.

`--framework <name>`	Override the detected framework
`--out <folder>`	Where to write the files (default: here)
`--force`	Overwrite files that already exist

whoami / logout

brandrail whoami | brandrail logout

Show or remove the saved sign-in.

rules

brandrail rules

List the rules.

Environment

BRANDRAIL_KEY API key for CI, from Dashboard → Connect → API keys. Otherwise the key saved by connect is used.