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 is supported with Reka UI and Svelte 5 with Bits UI, with every component except Direction in Svelte (Bits UI sets direction on each component).

npx @tesserai/cli init ./acme.tesserai.json

init adds the CLI to your project as a dev dependency, so npx @tesserai/cli runs that same version from then on. The examples below use tesserai as shorthand for npx @tesserai/cli.

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 run npx -y @tesserai/cli mcp with the project's absolute path, which uses the project's own copy of the CLI. Update the path if you move the project. For an existing project or another client, register it manually below.

One click

Adds the server to your editor for every project. Started this way, it asks the editor which folder is open and serves that project; if it can't tell, pass --dir as below.

Add to Cursor Install in VS Code

Claude Code

claude mcp add --transport stdio tesserai -- \
  npx -y @tesserai/cli 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 the path. If the editor cannot find npx, use its absolute path.

{
  "mcpServers": {
    "tesserai": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tesserai/cli", "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. 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.

Bring your look in import

npx @tesserai/cli import
npx @tesserai/cli import ./apps/web --dry-run
npx @tesserai/cli import --out system.tesserai.json

Already have a design system? Run import in the project and it becomes a tesserai system: colors for light and dark, fonts, body text size, corners, spacing and shadows. It reads the stylesheets your app loads (a shadcn theme, Tailwind v4 @theme, CSS variables, Sass and Less variables, or plain rules), design-token files (W3C DTCG, Tokens Studio), fonts set through next/font, and a Tailwind v3 config, as text.

It says what it found and the file and line each value is on, what it filled in to match, and what it left out and why. What it found is set exactly. It never changes your project, and your code never leaves your machine: only the resulting system is sent, to open it in the builder (saved to your account when that browser is signed in). --dry-run only prints the report; --out writes a file to import yourself.

A look that lives in code, like an antd, MUI or Chakra theme or a styled-components theme object, isn't something a file reader can follow. Connect your coding agent (below) and ask it to import the project's design system: it reads the code and hands tesserai what it finds, with the same report.

Analyze usage scan

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

Scan reports how the app uses its system: each component's uses and files, most used first, and each option's uses (a use without it counts for the default); components and options no use sets; overrides, where className, class, style or sx restyles a component, by what they change (margins, width and position aren't counted); the same override repeated on three or more uses, as a change to make in the system; generated files edited by hand since install; an adoption score; and hard-coded colors and sizes. Generated files are excluded from usage. --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.

--upload keeps the scan with its system in the builder, under Usage, where the team sees how each app uses the system and how that changes (Pro). It sends counts, kinds and class names: no source, and no paths but generated component files edited by hand. The project must follow its system's account link (Install in the builder, signed in) and be signed in with npx @tesserai/cli login.

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, antd, 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.

A component requires a different dependency version

init and sync check versioned component dependencies before writing files, including with --no-install. For example, generated Vue DataTable components require @tanstack/vue-table@^9; v8 APIs are incompatible. Migrate your existing table usage and install a compatible version, then retry. Dependencies are never silently upgraded across major versions.

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.