CLI reference

Every command supports --help. --json on commands that produce output gives machine-readable JSON.

The bundle is a single file under 1 MB. Distributed via npm; run with npx windcraft — no global install needed.

Authorize this machine for a project.

windcraft login [--api-key <key> --project-id <uuid>] [--json]

Without flags, opens a browser to /cli-auth?code=… and polls for up to 5 minutes. Stores credentials at ~/.windcraft/credentials (chmod 600).

windcraft logout

windcraft logout [--json]

Clears stored credentials. Idempotent — exits 0 with an info line when nothing is stored.

windcraft whoami

windcraft whoami [--json]

Shows the active project + key prefix. Exits 1 when not signed in.

windcraft init

windcraft init [--local] [--yes] [--cwd <path>]

Detects package.json, git remote, tailwind.config, Expo, CSS entry. Writes .windcraft/config.json, adds .windcraft/backups/ and .windcraft/cache.json to .gitignore.

By default init links a cloud project and pulls the initial sync (requires windcraft login).

`--local` (no account)

npx windcraft init --local

Scaffolds everything offline from a bundled starter theme — no login, no cloud. Writes a project-less config.json, a .windcraft/tokens.json, the Tailwind / CSS-vars / TS-types outputs, and the Claude skill. Then windcraft check and windcraft mcp run fully locally. --yes (or any non-interactive shell, e.g. CI) accepts the detected defaults. Upgrade later with windcraft login to sync a shared, editable design system across a team.

windcraft sync

windcraft sync [--json] [--force-dirty] [--commit] [--watch] [--watch-interval <s>]

Pulls the manifest and writes the generated files atomically with SHA-256 comparison; skips no-ops; backs up to .windcraft/backups/<iso>-<file>. Warns when the working tree is dirty.

--commit stages and commits files written by this run as a chore(windcraft): sync vN commit.
--watch keeps the CLI open and re-runs sync whenever the cloud manifest version changes (default poll interval 30s, min 5s).

Set WINDCRAFT_TELEMETRY=0 to disable the anonymous sync-event telemetry that sync otherwise logs.

windcraft check

windcraft check [--json] [--fix] [--no-cache] [--workers <n>]

Runs the static analyzer over .tsx / .jsx files matched by the include patterns from .windcraft/config.json. Exits 1 on errors, 0 on warnings or clean.

--fix applies edits where rules implement fix().
--no-cache skips the persistent .windcraft/cache.json.
--workers <n> runs parsing in N Piscina worker threads — useful for

500-file projects. Also honours WINDCRAFT_WORKERS.

windcraft mcp

windcraft mcp [--http <port>] [--host <addr>]

Run as an MCP server. Default transport is stdio — add to ~/.cursor/mcp.json or ~/.claude.json.

--http <port> exposes a Streamable HTTP transport on <host>:<port> (default host 127.0.0.1) for remote consumers. The HTTP transport is authenticated — clients must send the project API key as a bearer token (Authorization: Bearer wc_live_…).

Exposes 6 tools (get_design_tokens, get_component_contract, get_design_rules, validate_component_code, get_platform_mirror, get_page_pattern) and 4 resources (windcraft://project/tokens|contracts|rules|patterns). Manifest cached 60s with stale fallback on API outage.

Configuration file

.windcraft/config.json lives at your repo root:

{
  "projectId": "…",
  "include": ["app/**/*.tsx", "src/**/*.tsx"],
  "exclude": ["**/*.stories.tsx", "**/*.test.*"],
  "outputs": {
    "tailwind": "tailwind.config.ts",
    "cssVars": "app/globals.css",
    "rnTheme": "theme.ts",
    "tsTypes": "windcraft.types.d.ts",
    "tokens": "windcraft.tokens.json",
    "claudeSkill": ".claude/skills/windcraft.md"
  }
}

Set any output to null to skip writing that file.

On this page