CLI reference

Every tessera command. Each runs in the nearest folder above the current one that looks like a project, or the one named with --root. See The command line for how they fit together.

Options for every command

• --root <folder>: Run in this project instead of the nearest one above the current folder.
• --no-color: Print without color. The color is off anyway when the output is not a terminal, and when NO_COLOR is set.
• --help, -h: Say what a command does and what its options are.
• --version, -v: Print the version.

init

tessera init [folder] [--preset tessera|tailwind|none]

Writes the app (a layout, an index page, main.ts) and, per the preset, the design system. tessera writes a small design system of its own (warm paper neutrals, one green accent: colors, spacing, radii, type, shadows, light and dark themes, three components) and a styled index page; the docs are styled by the same tokens. tailwind writes a full system/ built from the default theme of Tailwind (every color, the spacing scale, radii, type, shadows, easing and more as tokens, light and dark themes, three components) and a styled index page. none writes no tokens, themes or components, and example files with the examples commented out. In a terminal it asks which preset; --preset answers it, and with neither it uses tessera. It adds the scripts (dev, build, preview, check) and the dependency to an existing package.json, never overwrites a file, and lists what it left alone.

Option
--preset <name>	tessera, tailwind or none. Skips the question.
--link <folder>	For working on Tessera itself: depend on this checkout of the package instead of the published version.

dev

tessera dev [--port <n>]

Starts the dev server with no configuration files: the CLI supplies the Vite config (with the Tessera plugin) and the HTML page. A project that has its own vite.config.ts or index.html uses them instead.

Option
--port <n>	The port to serve on. Default 5173, or the next free one.

build

tessera build [--prerender]

Builds with the same zero-configuration setup as tessera dev. Each page is its own chunk. With --prerender, every page that has no parameters is also rendered to HTML after the build: / is index.html, /about is about/index.html, and the not-found page is 404.html, each with its content, styles and title, so it shows at once and a search engine reads it. There is no hydration: when the script loads it replaces the content with the live page, which is the same page. A route with a parameter (/blog/[slug]) is skipped, and so is a page that cannot be rendered outside a browser (its script reads window); each is named with the reason and still works as before.

Option
--prerender	Render the pages that have no parameters to HTML after the build.

preview

tessera preview [--port <n>]

Serves dist/, the output of tessera build, to check it locally.

Option
--port <n>	The port to serve on.

check

tessera check [--fix] [--json]

Runs what a build runs, without bundling: the tokens build, every .tess file (contract, template, style rules, contrast, links, layouts), route conflicts, and auto-imports used in plain .ts files. Per-path severity and the baseline are applied. Exits 1 if there is any error; warnings never fail.

Option
--fix	Apply the fixes that are unambiguous (an exact match to one token, or a typo with one candidate). Never changes how the default theme renders.
--json	Print the result as JSON.

lint

tessera lint [paths...] [--tokens <folder>] [--fix] [--json]

The style rules of tessera check, on the CSS of any project, with or without Tessera components. It reads .css files and the <style> of .vue, .svelte, .astro and .html files (not Sass, Less or Stylus), with design tokens as custom properties such as var(--t-space-4), and reports raw values that are off the token scale (with the nearest token), colors that are not tokens, var() names that are not tokens (with the one meant), tokens of the wrong kind for a property, primitive tokens used directly, deprecated tokens, and text and background token pairs that fail contrast in any theme. Tokens come from DTCG files: --tokens <folder>, the tokens of tessera.config.ts, or system/tokens. The config's governed, contrast, primitives and per-path severity (with a reason and an expiry) apply, --fix applies the unambiguous fixes, and --baseline records today's violations in tessera.lint-baseline.json so existing code can adopt the rules and only new violations fail. With no paths it lints the project folder, skipping node_modules, build output and dot folders. Exits 1 if there is any error.

Option
--tokens <folder>	The DTCG token files to check against.
--var-prefix <prefix>	The prefix of the custom properties that are tokens, if your build names them differently. Default --t-.
--fix	Apply the fixes that are unambiguous.
--baseline	Record today's violations, so only new ones fail.
--prune	Lower the baseline to what files have now. Never raises it.
--json	Print the result as JSON.

a11y

tessera a11y

Sets up the accessibility tests Tessera generates from your contracts: a test file in each components folder (system/components, app/components) that asks for them, a Vitest browser-mode configuration if the project has none, the dev dependencies (vitest, @vitest/browser, playwright, axe-core) and a test:a11y script in package.json. Components that need data to be shown, such as a combobox, get example options. It never overwrites a file, and it does not install anything: it ends with the commands to run. The tests run in a real browser. Set TESSERA_A11Y_CHANNEL=msedge (or chrome) to use one that is already installed.

baseline

tessera baseline [--prune]

Records today's violations per file and per rule in tessera.baseline.json. With a baseline, check and builds fail only on violations beyond the recorded counts. Contract errors are never baselined.

Option
--prune	Lower the recorded counts to what files have now. Never raises a count.

report

tessera report [--json]

Measures what styles contain: the tokenized versus hand-written declaration ratio in total and per directory, every raw() with its reason and expiry, severity exemptions, remaining baseline debt, contract coverage, where generated accessibility suites exist, and usage of deprecated components.

Option
--json	Print the report as JSON, for CI.

tokens build

tessera tokens build [--out <folder>]

Resolves the design tokens and writes tokens.css, tokens.d.ts and manifest.json. Exits 1 with the diagnostics if the tokens do not build.

Option
--out <folder>	Where to write. Default .tessera/tokens.

docs

tessera docs [--port <n>] [--edit] [--static [--out <folder>]]

Runs a documentation app for the project: a page for every component (description, a live preview with a control for each variant, the variant, part, state, slot and event tables, usage examples, the tokens its styles use and the source), a page for every token group (the value in every theme after aliases are followed, with swatches and specimens), a contrast table, and an overview with the coverage report that tessera report prints (also downloadable as JSON). Theme and density switchers are always visible. Nothing is written by hand: add a component with a valid contract and it appears, with its controls, without a restart. A Name.docs.md beside a component adds guidance prose, and a fenced tess live block in it runs as a real example. --static writes a folder of plain files (default docs-dist) that any file server can host. An Export page offers the tokens as DTCG or Tokens Studio files, as a zip or one by one. --edit adds a page to bring in a token export, each change validated by the compiler first, on this computer only.

Option
--port <n>	The port to serve on.
--edit	Let the docs bring in a token export (the Export page needs no flag): the change is previewed and checked by the compiler first. Local only, behind a key printed at startup.
--static	Write static files instead of serving.
--out <folder>	With --static, where to write. Default docs-dist.

elements

tessera elements [--out <folder>] [--prefix <p>] [--all]

Builds the design system's components (the ones in system/components) as standard custom elements, so teams that do not use Tessera can use the system from any framework or from plain HTML. The folder is self-contained: elements.js has the elements and the runtime they need, elements.css has the design tokens (with their themes) and the components' styles, react.js and react.d.ts wrap each element as a React component (no JSX, no build step), elements.d.ts has the types, custom-elements.json is the manifest editors and docs tools read, and README.md says how to use it. Variants and props are attributes and properties, what a component emits is a DOM event with its payload in detail, and slots are children. Tags are <t-button>, <t-accordion-item>: the prefix, a hyphen and the name in kebab case.

Option
--out <folder>	Where to write. Default dist-elements.
--prefix <p>	The tag prefix: lowercase letters and digits. Default t, so <t-button>.
--all	Build the components in app/components too.

format

tessera format [files...] [--check] [--stdin-filepath <file>]

Formats the .tess files of the project (or the files you name) with Prettier and the Tessera plugin, so formatting does not depend on an editor extension. Each block is formatted with the right tool: the contract as JSONC, the script as TypeScript, the style as CSS; the template is only re-indented. It uses the Prettier installed in the project and its Prettier configuration, and says how to install Prettier if the project has none. With --check it changes nothing and exits 1 if any file is not formatted.

Option
--check	Report unformatted files and exit 1 instead of changing them.
--stdin-filepath <file>	Read one file from standard input and write the formatted text to standard output, for an editor that formats a buffer through an external command.

diff

tessera diff <git-ref> [--to <git-ref>] [--changelog [--version <v>]] [--json] [--fail-on-breaking]

Compares the contracts and tokens in the working tree (or at --to) with another version, and classifies each change. Breaking: a removed or renamed component, variant, value, part, state, slot, event, token or theme; a changed role, behavior or default; a changed token type; a value change that flips a contrast result in any theme; and one that moves a token past its neighbour in a scale. Additive: something new, or newly deprecated. Cosmetic: any other token value change. A rename a codemod can apply says so. The ref is read without touching the working tree or the index.

Option
--to <ref>	Compare with this ref instead of the working tree.
--changelog	Print a changelog section in Markdown.
--version <v>	With --changelog, the heading for the section.
--json	Print the changes as JSON.
--fail-on-breaking	Exit 1 if any change is breaking, for CI.

codemod

tessera codemod [--write] [--json]

Reads the renames the design system declares (renamedFrom on a component or a token, renamedValues on a contract) and rewrites the project to match: component tags and explicit imports, static variant values on the tags of the component and in its own style selectors, and token references in styles and in other token files. Without --write it only lists the changes. It reads the lexical blocks it can name and reports, as needing a hand, a computed value that still mentions an old one. The declarations themselves are never changed. A component whose contract is not valid (its name does not match its file, say) is not loaded, so a rename it declares cannot be read: the codemod lists it as skipped and exits 1, never "nothing to do".

Option
--write	Apply the changes. Without it nothing is written.
--json	Print the changes as JSON.

tokens import

tessera tokens import <file or folder...> [--format dtcg|tokens-studio] [--out <folder>] [--force]

Reads tokens another tool wrote and writes Tessera token files: strict DTCG 2025.10 files, a DTCG Resolver document (its default context becomes the base, its other contexts become themes, and the files it names are read for you), or a Tokens Studio or Penpot export (a single file, or the multi-file layout with $themes.json). The format is detected unless --format says. Values from earlier drafts and from tools that write strings ("#ff0000", "16px") become the strict forms. Aliases are kept as aliases. What Tessera cannot represent (a gradient, a typography composite, a math expression) is skipped, reported as T1016 and kept under $extensions.tessera.skipped, so export puts it back. The result is built before anything is written, and nothing is written if it has errors. It never overwrites a file: use --out for a new folder, or --force.

Option
--format <name>	dtcg or tokens-studio. Detected when left out.
--out <folder>	Where to write. Default: the project's tokens folder (system/tokens).
--force	Replace token files that already exist.

tokens export

tessera tokens export [--format dtcg|tokens-studio] [--out <folder>]

Writes the project tokens for other tools. dtcg (the default) writes strict DTCG 2025.10 token files and tessera.resolver.json, a Resolver document with the base as a set and each attribute (theme, density) as a modifier with a context per theme. tokens-studio writes one file per set, $themes.json and $metadata.json, with colors and dimensions as the strings that plugin reads. Aliases are never flattened.

Option
--format <name>	dtcg (default) or tokens-studio.
--out <folder>	Where to write. Default .tessera/export/<format>.

new component

tessera new component <Name>

Writes app/components/<Name>.tess with a valid contract. Names are PascalCase and global, so a name another component has is refused.

new page

tessera new page <path>

Writes app/pages/<path>.tess. It refuses a path that would conflict with an existing route (naming both files) or that cannot be a route.

eject

tessera eject <Name> <NewName>

Copies a system component under a new name and records forkedFrom (the component and the version) in its contract, so owning a copy never means silent drift.

explain

tessera explain <code>

Prints the same explanation as the error reference, from the error registry. Works offline.

manifest

tessera manifest

Writes .tessera/manifest.json (every component with its contract and usage examples, every token with its tier and its value in every theme, the routes and the rules the compiler enforces) and .tessera/custom-elements.json, the same components in the custom-elements.json format that editors and component tooling read. tessera dev and tessera build keep the manifest current, so this is for CI and for tools that run before a build.

mcp

tessera mcp

Starts a Model Context Protocol server on standard input and output. A client lists and searches components, fetches a component contract, lists tokens by role, resolves a raw value to the nearest token, and validates a snippet with the compiler, getting the same errors as tessera check. It never writes a file. Configure a client with the command npx tessera mcp.

agent-files

tessera agent-files [--force]

Writes AGENTS.md (the rules for working in this project, and its components) and llms.txt from the manifest, and refreshes .tessera/manifest.json. A file that exists and was not generated by Tessera is left alone.

Option
--force	Replace AGENTS.md and llms.txt even if you wrote them.

Exit codes: 0 on success, 1 on any error, with the message printed to standard error.