Your design system, in your workflow.

Get started

You need Node.js 22 or newer and a project using Tailwind CSS 4. React is supported with Base UI, Radix, or React Aria. Vue with Reka UI and Svelte 5 with Bits UI are beta targets; their component coverage can differ.

The CLI in this repository is currently private and versioned 0.0.0. Run it from a checkout; these instructions do not assume an npm release exists.

# In your Tesserai checkout, once
pnpm install --frozen-lockfile
pnpm --filter @tesserai/cli build

# From your application, using the checkout's absolute path
node /path/to/tesserai/packages/cli/bin/tesserai.js init ./acme.tesserai.json

Replace /path/to/tesserai with your checkout. The examples below use tesserai as shorthand for node /path/to/tesserai/packages/cli/bin/tesserai.js. You can make that a shell alias. For MCP, use the absolute executable and script paths instead of an alias.

Download a bundle from the builder, or use its share link. In a monorepo, pass --dir ./apps/web to target the app. Paths given as bundle inputs or --out are relative to your shell's working directory.

Install a system init

npx @tesserai/cli init ./acme.tesserai.json
# Or follow the design in the builder
npx @tesserai/cli init https://your-tesserai-host/s/AbCdEf123456 --dir ./apps/web
# Review generated files before installing dependencies
npx @tesserai/cli init ./acme.tesserai.json --no-install

Init detects your framework, package manager, source directory, and import aliases. It writes theme CSS, component source, helper files, and the tesserai/ bundle and manifest. Import the generated stylesheet in your app; follow the command's printed setup notes. Commit the generated code and tesserai/ files so teammates share the same design.

--dir <path>

Project directory; defaults to the current directory.

--base <name>

Choose a React primitive library: base-ui, radix, or react-aria. Vue and Svelte targets follow the detected project.

--prefix <name>

Prefix Tailwind classes, such as acme:bg-primary. Use --prefix none to remove the prefix.

--no-install

Write code without running the package manager.

--no-lint

Skip the generated lint configuration and its dependencies.

--live

Install current work from a link instead of its latest release.

Keep it in sync sync

npx @tesserai/cli sync --dry-run
npx @tesserai/cli sync
npx @tesserai/cli sync ./updated.tesserai.json
npx @tesserai/cli sync --dry-run --json > sync-plan.json

A project installed from a link follows that link. Sync uses its latest release when one exists; --live uses current work. A file-based project uses its local tesserai/design-system.json unless you supply a new bundle or link.

Your edits are preserved. If you changed a generated file, sync keeps it and writes the proposed replacement beside it as .tesserai-new. Compare them and merge what you want. Back up the project before using --force, which overwrites locally edited generated files.

--dry-run

Calculate planned changes without writing project files.

--verbose

Show diffs for preserved files.

--json

Emit one JSON result to stdout, including file outcomes, warnings, release notes, and breaking changes. Progress goes to stderr.

--force

Replace edited generated files. Review with a dry run first.

--live

Follow current work rather than a release.

--dir <path>

Select the project.

If the source cannot be reached, sync may retain the local bundle and report a warning. Check warnings in JSON when a script requires a successful remote update. Only a missing release (404) falls back to current work.

Connect your coding agent mcp

Tesserai runs a local MCP server over stdio. The init command registers it in .mcp.json and, when a .cursor folder exists, .cursor/mcp.json. Existing server entries are preserved. The MCP process reads the local project and needs no model-provider API key.

Generated entries use absolute Node, CLI, and project paths for fast, reliable startup. Update these paths when moving a checkout or sharing configuration with another machine. For an existing project or another client, register it manually below.

Claude Code

claude mcp add --transport stdio tesserai -- node \
  /absolute/path/to/tesserai/packages/cli/bin/tesserai.js \
  mcp --dir /absolute/path/to/your-app

Use /mcp in Claude Code to inspect the connection. See Claude Code's MCP setup reference for scopes and client settings.

Cursor and JSON-based clients

For Cursor, put this in your project's .cursor/mcp.json. Replace both paths. If the editor cannot find node, use its absolute path too.

{
  "mcpServers": {
    "tesserai": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/tesserai/packages/cli/bin/tesserai.js",
        "mcp", "--dir", "/absolute/path/to/your-app"
      ]
    }
  }
}

Other clients can use the same command and arguments in their local-server settings. See Cursor's MCP reference. Restart or reconnect the server after updating the CLI build. A quiet terminal after npx @tesserai/cli mcp is normal: stdout carries only the MCP protocol.

Build with MCP

1. Read outline for local context. It starts a background freshness check for linked systems. Its cached status is labeled; use {"refresh": true} when you need a fresh remote check.
2. Call sync if the design changed. Use {"dryRun": true} to review the planned files.
3. Read component_guide for imports and props, and example_page for a complete page in the project's framework.
4. For a local design change, use list_operations and describe_operation, then preview apply_changes. Apply after reviewing its contrast and guideline report.

{
  "summary": "Rounder corners",
  "ops": [{ "op": "radius.set", "input": { "base": 12 } }],
  "preview": true
}

Send this input to apply_changes. Set preview to false to save and regenerate. Invalid changes do not write the system. Existing component edits are preserved using the same conflict behavior as CLI sync.

Linked projects are edited in the builder, then synced. MCP refuses local apply_changes that the next sync would replace. To intentionally make a local copy independent of the builder, back it up and remove tesserai/source.json.

Concurrent edits in one MCP session are serialized. Overlapping sync and MCP design changes from another process get a prompt retry message. Local reads do not wait on the network; explicit remote freshness checks have a five-second deadline. Generating a whole project, scanning many files, downloads, and package installation take longer than a local read.

MCP tools

All 15 tools are listed below. Read tools declare themselves read-only to the client. apply_changes and sync can write files; their preview options keep the project unchanged.

Tool inputs are JSON objects. Tool failures return isError: true with an explanation; repair the input or project and try again. Editing the local bundle is detected on the next read without restarting the server.

Check adoption scan

npx @tesserai/cli scan
npx @tesserai/cli scan --json
npx @tesserai/cli scan --fix --json

Scan reports component usage, an adoption score, and hard-coded colors and sizes. Generated files are excluded. --fix rewrites supported exact matches; review the diff before committing. With --fix --json, the result includes a fixed map of replacement counts per file and the post-fix scan.

Scanning is a source heuristic, not a browser audit. It can miss computed styles or flag values outside styles. --dir selects the project. Scan finding issues does not itself set a failing exit code; inspect the JSON for your CI policy.

Use another stack export

npx @tesserai/cli export scss --out theme.scss
npx @tesserai/cli export ts --brand acme --out theme.ts
npx @tesserai/cli export swift

Available formats: scss, ts, panda, stylex, mui, mantine, chakra, swift, kotlin, and dart. These export the design tokens for another stack; they do not generate native UI screens.

--brand <id> selects a brand, --out <file> writes a file, and --dir selects the project. Without --out, the export goes to stdout.

Browse the components storybook

npx @tesserai/cli storybook
npx @tesserai/cli storybook --no-install --dir ./apps/web

Generate a Storybook with a story per component, theme and density controls, and accessibility checks. Sync keeps the stories current. Use the generated project's Storybook script to start it. --no-install leaves dependency installation to you.

Work with private systems login / logout

npx @tesserai/cli login https://your-tesserai-host
npx @tesserai/cli init https://your-tesserai-host/systems/00000000-0000-0000-0000-000000000000
npx @tesserai/cli logout https://your-tesserai-host

Use the private system's real URL from the builder. Login prints a verification link and opens the browser; approve the device there. Over SSH, set TESSERAI_NO_BROWSER=1 to print the link without opening a browser. Omit the host to use the CLI's default host, shown by npx @tesserai/cli --help.

Credentials are saved per host in ~/.config/tesserai/credentials.json with owner-only permissions. TESSERAI_CONFIG_DIR overrides the directory. Keep credentials out of version control and MCP configuration; the MCP server uses the same saved login.

Diagnose a project doctor

npx @tesserai/cli doctor --dir ./apps/web
npx @tesserai/cli doctor --json

Doctor checks project configuration, the design-system bundle, manifest, source link, preserved edits, and the write lock. It reads local files only. Errors set exit code 1; warnings are reported without failing the command. Remote access and installed dependency versions are not tested.

Use npx @tesserai/cli --help, npx @tesserai/cli sync --help, and npx @tesserai/cli --version without opening a project. Invalid commands and unsupported flags fail before work starts. Normal command failures go to stderr with exit code 1.

Troubleshooting

No design-system.json or manifest

Check --dir points to your app, then run init. MCP does not install a project implicitly.

“Signed out” or a private link cannot be read

Run login for that link's host. Confirm the signed-in account has access to the system.

Source timed out or remote changes are missing

Check the connection and retry. Ordinary MCP outlines use cached freshness for up to 30 seconds. Call outline with refresh: true to wait for a fresh check. A failure is shown explicitly.

Another tesserai command is writing

Wait for it to finish, then retry. If the process crashed, inspect .tesserai-write.lock for its PID and remove the lock only after confirming that process has stopped.

Generated files have .tesserai-new neighbors

Your hand edits were kept. Compare and merge the proposed code. Use doctor to list unresolved copies; use sync --force only when you intend to replace the edited files.

MCP is disconnected or produces invalid protocol output

Use an absolute Node/script path and an explicit --dir. Run doctor in a terminal. Remove shell wrappers that print banners to stdout, then reconnect in your editor.

Development changes are not reflected in the CLI

Run pnpm --filter @tesserai/cli build again. Maintainers can set TESSERAI_SOURCE=1 to run TypeScript directly. TESSERAI_OFFLINE=1 skips web-font downloads in tests; it does not disable source-link requests.