Command line
The taisho command compiles the CSS with your brand, recompiles it as you save, and checks
that your classes exist. It ships with the package, so there is nothing else to install.
The commands
Install @taishods/core in the project (Node 22.18 or newer is required) and run it with npx. taisho --help lists everything below.
npm i -D @taishods/core
npx taisho --help| Command | What it’s for |
|---|---|
| taisho init | Creates the project’s taisho.config.ts. |
| taisho generate | Compiles the config to a self-contained folder: the CSS with your brand and the behavior JS. |
| taisho watch | Generates once, then regenerates what changed every time you save a file. |
| taisho check | Flags misspelled system classes and variables. |
| taisho mcp | Starts a local MCP server so an AI assistant can look up components, utilities, and your theme. |
| taisho migrate | Moves code from another system to TaishoDS Core and lists what it couldn’t convert. |
The steps to get started, from the CDN or with the package, are in Installation, and the configuration file is in Theming.
taisho init
Creates taisho.config.ts in the current folder, or in the one you pass
(taisho init [folder]). If one already exists it is left as is: the command says so and
exits with 1.
| Option | Effect |
|---|---|
| --yes, -y | Skips the questions and writes the config with the defaults. |
| --install-icons | Installs lucide-static (the icons) without asking. |
| --lang <language> | Language of the config and the messages (Spanish or English); with this option it isn’t asked. |
In a terminal it asks, in this order: the message language (the system’s is suggested), the brand color as hex, the
theme name, whether fonts come from the system or from Fontsource, the folder for your own icons, and the output
folder for the CSS and JS. Enter accepts each suggestion. Without a terminal (in CI, for example) or with --yes, it asks nothing and writes the defaults.
The suggested output folder depends on the project: public/taisho if public/ exists, static/taisho if static/ exists, and ./taisho otherwise. If the package.json declares a bundler
or a framework (Vite, SvelteKit, Astro, Next, and similar), it suggests ./taisho even when those
folders exist, because the CSS is imported from code and those bundlers don’t let you import what sits in public/. The answer is saved as out in the config.
The Lucide icons don’t ship with the Core: they live in the lucide-static package. If the project
has a package.json and doesn’t have it installed yet, the last question is whether to install it.
On yes, init installs it as a development dependency with the project’s package manager (npm,
pnpm, Yarn, or Bun, depending on the lockfile it finds) and shows the command it runs. If the install fails, say with no
network, init doesn’t fail: it warns and leaves the command to run by hand. Without a terminal or
with --yes it installs nothing and prints the exact command; --install-icons installs it without asking.
taisho generate
Compiles the config to the output folder: theme.css (your theme’s tokens), fonts.css, the system CSS, and the behavior JavaScript
(taisho.core.js and its modules). With content in the config, the CSS is taisho.css and holds only what your files use; without content, it is
the complete taisho.full.css. If the project uses icons, it also writes the sprite.
| Option | Effect |
|---|---|
| --config <ruta> | Path to the config. Defaults to ./taisho.config.ts. It can also be passed as an argument. |
| --out <carpeta> | Output folder. Overrides the config’s out; with neither, ./taisho next to the config. |
| --strict | Exits with 1 if there was any warning. The output is still written. |
npx taisho generate
npx taisho generate --out public/taisho
npx taisho generate --strictWhen it finishes it prints the exact lines to paste into your HTML, with the path the browser sees (without public/ or static/, and with forward slashes on Windows too):
✅ Generated in public/taisho/
This goes in your HTML, in this order:
<link rel="stylesheet" href="/taisho/fonts.css">
<link rel="stylesheet" href="/taisho/theme.css">
<link rel="stylesheet" href="/taisho/taisho.css">
<script type="module" src="/taisho/taisho.core.js"></script>Icons come from the lucide-static package. generate neither installs it nor
asks: if the code uses icons that don’t resolve because the package is missing, it says so with the command to install it
and exits with an error; if the code uses no icons, it says nothing. There is more in Icons.
taisho watch
Generates once and keeps watching: every time you save a content file, the config, or an SVG in src/icons/, it regenerates only what changed. Press Ctrl+C to exit, with code 0. If something
fails (an invalid config, an icon that doesn’t exist), it shows the error, keeps the previous output, and keeps
watching.
| Option | Effect |
|---|---|
| --config <ruta> | Path to the config. Defaults to ./taisho.config.ts. It can also be passed as an argument. |
| --out <carpeta> | Output folder, same as in generate. |
✅ taisho/ up to date (3 files, 215 ms). Watching 9 content files, the config, and src/icons/. Ctrl+C to exit.
+ w.html → no changes (12 ms)
⚠ w.html:1: "gap-bse" isn't a DS class, so it isn't emitted. Did you mean "gap-base"?A limit
taisho.config.ts imports another file (your colors in a marca.ts,
say), a change to that file isn’t detected. Touch the config or restart taisho watch.taisho check
Checks your code against the system and flags what won’t be styled. It works without generate and without a config, so it also works as a CI check.
| Option | Effect |
|---|---|
| [rutas…] | Files, folders, or globs to check. Without them, the config’s content or, with no config, the whole project except node_modules, dist, build, and coverage. |
| --config <ruta> | Path to the config, which provides the content and the vocabulary. |
| --format <text|json> | Output format. Defaults to text; json prints the result to stdout and sends the summary to stderr. |
| --other-scale | Also flags sizes whose number means something else in other systems (p-4 is 4 px here). Off by default. |
npx taisho check # the whole project
npx taisho check src # one folder
npx taisho check 'src/**/*.{svelte,css}' # only these files
npx taisho check --format json # for a program to readEach warning is one line with file:line:column, the rule, and the message, with a replacement
when there is one:
aviso.html:1:23 unknown-class "bg-brnad-500" isn't a DS class, so it isn't emitted. Did you mean "bg-brand-500"?
taisho check: 1 file checked, 1 warning.What it flags
| Rule | What it flags |
|---|---|
| unknown-class | A system class that doesn’t exist: a typo, a value outside the scale, or a name from another system. The project’s own classes aren’t flagged. |
| missing-ts | An element with system classes but without the ts class, which gets no styles without it. |
| ignored-attribute | An attribute that isn’t read as classes (its name doesn’t end in class) with the ts class and system classes in the value: those classes aren’t emitted. |
| legacy-prefix | A class with the ts- prefix, which is no longer used: write it without the prefix and with the ts class on the same element. |
| unknown-var | A var(--ts-*) or var(--color-*) that no theme declares. |
| other-scale | Only with --other-scale: a size with another system’s name and a different value. |
Classes are read in the literal class and className attributes of .html, .svelte, .vue, .astro, .jsx, and .tsx files. A class built
while the code runs isn’t validated. .md files are only checked when you ask for them.
Output for programs
With --format json, stdout carries only a JSON object with version, files, and the warnings list; each warning has file, line, column, rule, severity, code, params, message, and, when there is a clear replacement, suggestion. The summary goes to stderr. To decide something in a script, read code and params, which are the same in both languages; the text of message can change. A new rule arrives as a warning (severity: "warning"),
which doesn’t change the exit code.
taisho mcp
Starts an MCP server over standard input and output, so an AI assistant can look up the project’s components, utilities, and theme while it writes. It is local and read-only: it writes no files, makes no network calls, and sends no telemetry. The assistant’s client launches it, so it isn’t run by hand; it exits with 0 when the client closes the input. How to set it up and what each tool replies is in AI assistants.
| Option | Effect |
|---|---|
| --config <ruta> | Path to the config. Defaults to ./taisho.config.ts; without a config it uses the default theme. The config’s folder becomes the project root. |
| --lang <language> | Language of the sheets and messages (Spanish or English). Defaults to the config’s lang and, failing that, the system’s. |
taisho migrate
Moves code written for another system to TaishoDS Core’s vocabulary and lists what it couldn’t convert. Without --write it only reports, so it is safe to run. The source is chosen with --from; each one is explained in the migration guide under Foundations. Without --from, or with a source that doesn’t exist, it exits with 2.
| Option | Effect |
|---|---|
| --from <origen> | Which system to migrate from. Required. |
| [rutas…] | Files or folders to check; they replace content. |
| --write | Applies the changes. Without it, it only reports what would change. |
| --config <ruta> | Path to the config, which provides the content and the vocabulary. |
Common options and exit codes
taisho --help shows the help and taisho --version the version. taisho with no arguments shows the help and exits with 0. A CI job can tell “the code has
problems” (1) from “the command couldn’t run” (2):
| Code | Meaning |
|---|---|
| 0 | It ran and nothing went wrong. In check, no warnings of severity error. |
| 1 | It ran and what you asked for failed: an invalid config, a generation error, warnings with --strict, errors in check, a taisho.config.ts that already exists (init), or a Node older than 22.18. |
| 2 | Usage error: an option that doesn’t exist or doesn’t apply to the command, an option without its value, a command that doesn’t exist, a --lang value that isn’t supported, or a check that couldn’t run. |
Message language
taisho speaks Spanish or English: messages, errors, help, and reports. The language comes,
in this order, from --lang es or --lang en (valid on any command),
from the lang option in taisho.config.ts, and from the system language.
No command asks for it except init, so a CI job never sits waiting for an answer. The
language changes neither the CSS nor the exit codes.
npx taisho check --lang en