Reference
CLI reference
onsystem is one command. With no command it is the MCP server an agent starts; check, inspect, export and init are for the terminal and CI. With nothing installed, run it through npx; installed as a dev dependency, which pins the version for the team and CI, npx onsystem runs that install:
npx -y onsystem check .npx onsystem check .pnpm dlx onsystem check .pnpm exec onsystem check .yarn dlx onsystem check .yarn onsystem check .bunx onsystem check .bunx onsystem check .It needs Node.js 20.19 or later. The options are the ones onsystem --help prints, listed under the commands that take them, and a test keeps this page and the help in step.
onsystem,onsystem serve- What it does
- Starts the MCP server on stdio, for an agent (set up your agent)
onsystem check <paths...>- What it does
- Lints files, folders or globs with the rules
check_uiruns, and exits 1 on errors (CI and baselines)
onsystem inspect- What it does
- Prints what it read: where it found the design system, the components with their props, variants and parts, and the tokens by category
onsystem export --format <format>- What it does
- Prints the tokens it found as a DTCG 2025.10 file (
dtcg) or a DESIGN.md (design-md) (export)
onsystem init- What it does
- Writes
onsystem.config.jsonfrom what it found, checks the project once and offers to record the findings as a baseline
onsystem help- What it does
- Prints the help, as
--helpdoes
| Command | What it does |
|---|---|
onsystem, onsystem serve | Starts the MCP server on stdio, for an agent (set up your agent) |
onsystem check <paths...> | Lints files, folders or globs with the rules check_ui runs, and exits 1 on errors (CI and baselines) |
onsystem inspect | Prints what it read: where it found the design system, the components with their props, variants and parts, and the tokens by category |
onsystem export --format <format> | Prints the tokens it found as a DTCG 2025.10 file (dtcg) or a DESIGN.md (design-md) (export) |
onsystem init | Writes onsystem.config.json from what it found, checks the project once and offers to record the findings as a baseline |
onsystem help | Prints the help, as --help does |
At a monorepo root with no design system of its own, every command works per project: each file is checked against the design system of the nearest folder with a config, a components.json or a package.json, and inspect lists every project (monorepo roots).
A command given another command's option exits 2: check . --out report.json would write no file. serve only says on stderr that it ignores the option, and starts, so a stale argument in an agent's MCP config does not leave the agent without the server.
Options for every command
Link to the section Options for every command--root <dir>- What it does
- The project root. By default, the folder of the file
--confignames, or the working directory, or the project around it (below)
--config <file>- What it does
- The config file. By default, the first of
onsystem.config.json,onsystem.config.ts,onsystem.config.mts,onsystem.config.jsandonsystem.config.mjsin the root; the TypeScript ones need Node.js 22.18 or later (config file)
--components <glob>- What it does
- Component sources, repeatable. By default, what zero config finds
--tokens <file>- What it does
- A token file, repeatable: a DTCG
.json, a stylesheet or aDESIGN.md(where tokens come from)
--docs <glob>- What it does
- Component docs in Markdown or MDX, repeatable
--no-cache- What it does
- Ignores the cache of what it read from the design system (in
node_modules/.cache/onsystem, or the system temp folder without anode_modules), and reads it all again
-h,--help- What it does
- Prints the help
-v,--version- What it does
- Prints the version
| Option | What it does |
|---|---|
--root <dir> | The project root. By default, the folder of the file --config names, or the working directory, or the project around it (below) |
--config <file> | The config file. By default, the first of onsystem.config.json, onsystem.config.ts, onsystem.config.mts, onsystem.config.js and onsystem.config.mjs in the root; the TypeScript ones need Node.js 22.18 or later (config file) |
--components <glob> | Component sources, repeatable. By default, what zero config finds |
--tokens <file> | A token file, repeatable: a DTCG .json, a stylesheet or a DESIGN.md (where tokens come from) |
--docs <glob> | Component docs in Markdown or MDX, repeatable |
--no-cache | Ignores the cache of what it read from the design system (in node_modules/.cache/onsystem, or the system temp folder without a node_modules), and reads it all again |
-h, --help | Prints the help |
-v, --version | Prints the version |
Run from a folder with no config, components.json, package.json or project.json (such as app/settings), check, inspect, export and init take the nearest folder above it with one as the root, as the Claude Code hook does, and check says so: Checking the project in ../... They keep the working directory when given --root, --config, --components, --tokens or --docs, in a folder with a baseline, and in the home folder; the home folder and the filesystem root are never taken. A folder with a components/ui or src/components/ui folder of its own is kept too, as a design system without a package.json, unless it is the project's src or app folder, or the project has a components.json or a config, which say where its components are. --root . keeps the working directory.
onsystem or onsystem serve starts the MCP server on stdio. An agent starts it from its MCP config; typed in a terminal, it says that it is waiting for an agent, and Ctrl+C quits. It answers the handshake right away and reads the design system in the background, then reads it again when the component, token or docs files, the config or the tsconfig change (how it works). Started at a monorepo root, it serves every project (how the server finds your project).
--no-watch- What it does
- Does not read the design system again when files change
| Option | What it does |
|---|---|
--no-watch | Does not read the design system again when files change |
onsystem check <paths...> lints the files, folders and globs it is given with the rules check_ui runs (rules). A folder stands for its .tsx and .jsx files; folders and globs leave out the design system's own component files, tests and stories, what the config's exclude adds and what git ignores. A file named outright is checked too, unless it is one of the design system's own component files (--include-design-system checks those) or --skip-excluded leaves it out (CI and baselines).
It exits with:
0when there are no errors, and no more warnings than--max-warnings.1when there are errors, or more warnings than--max-warnings.2when it could not check: an unknown option, an option of another command (such as--out), no paths given, an unknown--format, a--max-warningsthat is empty (an unset variable,--max-warnings=) or not a whole number, a broken config, paths that match no file, a file it could not read, a--baselinefile that does not exist (unless--update-baselinewrites it),--prune-baselinewith no baseline to prune, or, with--require-design-system, no design system or nothing to check.
--format <format>- What it does
pretty(the default),json,github(annotations on the pull request) orsarif(code scanning)
--max-warnings <n>- What it does
- Exits 1 when there are more than
nwarnings.--max-warnings=-1is no limit, as in ESLint (with=: a-1on its own reads as an option)
--update-baseline- What it does
- Records the current findings as accepted in the baseline, and exits 0 (adopting it in an existing codebase)
--prune-baseline- What it does
- Drops the baseline entries that no longer occur, and accepts nothing new
--baseline <file>- What it does
- The baseline file. By default
onsystem.baseline.jsonin the root, used whenever it exists
--ignore-baseline- What it does
- Reports every finding, in the baseline or not
--include-design-system- What it does
- Also lints the design system's own component files, which are skipped by default (
"includeDesignSystem": truein the config does the same)
--include-tests- What it does
- Also lints tests and stories (
*.test.tsx,*.spec.tsx,*.stories.tsx) in folders and globs
--skip-excluded- What it does
- Leaves out the files named outright that the config's
excludecovers, as folders and globs leave them out. The Claude Code hook passes it
--quiet-without-design-system- What it does
- Prints nothing and exits 0 when the project has no design-system components and no config (tokens alone are not a design system), for a hook installed across many projects
--require-design-system- What it does
- Exits 2 when no components or no color tokens are found, or when the folders and globs it is given leave no file to check, so CI cannot pass by checking nothing
| Option | What it does |
|---|---|
--format <format> | pretty (the default), json, github (annotations on the pull request) or sarif (code scanning) |
--max-warnings <n> | Exits 1 when there are more than n warnings. --max-warnings=-1 is no limit, as in ESLint (with =: a -1 on its own reads as an option) |
--update-baseline | Records the current findings as accepted in the baseline, and exits 0 (adopting it in an existing codebase) |
--prune-baseline | Drops the baseline entries that no longer occur, and accepts nothing new |
--baseline <file> | The baseline file. By default onsystem.baseline.json in the root, used whenever it exists |
--ignore-baseline | Reports every finding, in the baseline or not |
--include-design-system | Also lints the design system's own component files, which are skipped by default ("includeDesignSystem": true in the config does the same) |
--include-tests | Also lints tests and stories (*.test.tsx, *.spec.tsx, *.stories.tsx) in folders and globs |
--skip-excluded | Leaves out the files named outright that the config's exclude covers, as folders and globs leave them out. The Claude Code hook passes it |
--quiet-without-design-system | Prints nothing and exits 0 when the project has no design-system components and no config (tokens alone are not a design system), for a hook installed across many projects |
--require-design-system | Exits 2 when no components or no color tokens are found, or when the folders and globs it is given leave no file to check, so CI cannot pass by checking nothing |
check exits 2 when it is given --quiet-without-design-system with --require-design-system, or --prune-baseline with --update-baseline or --ignore-baseline. Output is in color in a terminal, unless NO_COLOR is set. The GitHub Action sets ONSYSTEM_CHANGED_LINES to a file of the lines a pull request changed; unset it if it is left over in a shell where you run check yourself.
inspect
Link to the section inspectonsystem inspect prints what it read from the design system: the root and config, where it found the design system (the detected line), the components with their props, variants and parts, the tokens by category, and what it could not read. At a monorepo root it lists every project. When it found nothing, see troubleshooting.
--explain- What it does
- Adds every candidate zero config looked at and why it was taken or not, the config it resolved to, the tokens that did not resolve and the components whose props did not
--format <format>- What it does
pretty(the default) orjson, which prints what it read as JSON, for scripts; another value exits 2
| Option | What it does |
|---|---|
--explain | Adds every candidate zero config looked at and why it was taken or not, the config it resolved to, the tokens that did not resolve and the components whose props did not |
--format <format> | pretty (the default) or json, which prints what it read as JSON, for scripts; another value exits 2 |
onsystem export --format dtcg or --format design-md prints the tokens it found as a DTCG 2025.10 file or a DESIGN.md, which other tools read (export). At a monorepo root, pass --root with one project.
--format <format>- What it does
dtcgordesign-md, whichexportneeds
--out <file>- What it does
- Writes to this file instead of stdout
| Option | What it does |
|---|---|
--format <format> | dtcg or design-md, which export needs |
--out <file> | Writes to this file instead of stdout |
onsystem init writes onsystem.config.json from what zero config found, or asks where the components, tokens and import path are when it found nothing. Then it checks the project once and offers to record the findings as a baseline, and in a terminal it offers to add a short section on onsystem to AGENTS.md or CLAUDE.md. It never replaces an existing config without --force. At a monorepo root it writes a config with only $schema, and in a design-system package it also declares the config in package.json and writes ONSYSTEM.md for the apps' teams (config file, design-system packages).
-y,--yes- What it does
- Writes without asking, and records the baseline
--force- What it does
- Replaces an existing config file
| Option | What it does |
|---|---|
-y, --yes | Writes without asking, and records the baseline |
--force | Replaces an existing config file |
Last updated