# CLI

> The unframework command builds every target's source tree, checks a project and prints its diagnostics, explains a diagnostic code and scaffolds a project.

The `unframework` command is how a design system turns its components into seven frameworks' code outside an app: it compiles every source to every target you configured, reports what it found in a form that people, agents and CI can each read, and starts new projects. Think of a release that ships last week's Vue output because nobody rebuilt it, a CI job that can't tell a warning from an error, or an agent that guesses what `UF3013` means instead of reading it.

The command comes with the `@uxfront/unframework` package and runs from the directory that holds your [`unframework.config.ts`](/docs/tooling/configuration). It has seven commands:

```bash
unframework build [--package] [--type-oracle syntactic|tsgo]
unframework check [--format pretty|json|sarif] [--type-oracle syntactic|tsgo]
unframework explain <code>
unframework init [--force]
unframework test [--target <t>]... [--update] [-- <vitest args>]
unframework visual [--target <t>]... [--baseline | --live] [--update] [--out <dir>]
unframework preview [--target <t>]... [--port <n>]
unframework preview build [--target <t>]... [--out <dir>]
```

## Exit codes

Every command exits with one of three codes, so a script or a CI step can tell a broken component from a broken setup:

| Code | Meaning                                                                                                                                                                                                        |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | Success, warnings and notes included, but for what [`strict`](/docs/tooling/configuration#fields) makes an error. For `preview`, a stop with `Ctrl+C`. For `preview build`, a site written                     |
| `1`  | Error diagnostics: in a source, because no source was found, or from a packager. A failed test, for `test`. An example that differs or declares props, for `visual`                                            |
| `2`  | A usage error, `init`'s refusal, a config that won't load or is invalid, a project `--package` can't ship, or a write error. For `test`, `visual` and `preview`, also a package they need that isn't installed |

## build

`build` compiles every `.uf.tsx` and `.uf.ts` file under `srcDir`, skipping `node_modules`, `outDir` and [examples](/docs/tooling/visual), and writes one tree per target to `<outDir>/<target>`. Each output sits in the directory its source has under `srcDir`. With the defaults, a project with one `src/Button.uf.tsx` and its stylesheet gets this for React and Vue, and a tree in each other target's own file names:

```txt
dist/react/Button.tsx
dist/react/Button.tsx.map
dist/react/Button.uf.tsx.css
dist/react/index.ts
dist/vue/Button.uf.tsx.css
dist/vue/Button.vue
dist/vue/index.ts
```

Each tree holds:

- **The outputs.** Each file equals what the compiler gives, byte for byte, but for the comment below.
- **The shared `.ts` modules** a source reaches, copied unchanged.
- **A source map** for a JavaScript or TypeScript output: `<file>.map` beside it, and a trailing `//# sourceMappingURL=<file>.map` comment. A `.vue`, `.svelte` or `.astro` file and a scoped sheet get neither, since the comment is written for JavaScript and TypeScript.
- **A barrel,** `index.ts`, which exports each exported component and composable by its name. A default export takes its component's name: `export { default as Button } from "./Button";`.

`build` cleans each `<outDir>/<target>` before it writes it, so change the source and build again rather than editing an output. A build with an error diagnostic from a compile, or with a config it refuses, cleans and writes nothing, so the last good build stays in place. A packager's failure is the exception: it comes after the trees are written ([Packaging](/docs/tooling/packaging#when-it-fails)). A successful build prints only its warnings and notes, on standard error.

`build` and `check` also report what no single component's compile can see:

- **[`UF7007`](/docs/reference/diagnostics#UF7007):** `srcDir` holds no source.
- **[`UF1104`](/docs/reference/diagnostics#UF1104):** two sources would write one file, or a barrel would export one name from two files.
- **[`UF7002`](/docs/reference/diagnostics#UF7002) at `/outDir`:** cleaning a target's tree would delete the project, a source or a file a source reads.
- **[`UF7002`](/docs/reference/diagnostics#UF7002) at `/srcDir`:** a source imports a child the search didn't find, or a shared module above `srcDir`, which no tree could hold beside the source.

`build --package` also writes a package you can publish, with every target in its framework's own format. [Packaging](/docs/tooling/packaging) covers it.

## check

`check` runs everything a plain `build` runs and writes no file, so it fails wherever such a build would. It doesn't run what `--package` checks, like a `package.json` with no `name` or a missing packager ([`UF7008`](/docs/reference/diagnostics#UF7008)), so a project `check` passes can still fail `build --package`. It prints the diagnostics on standard output, in the format you ask for:

- **`pretty`**, the default, prints a code frame for each, and nothing when there are none.
- **`json`** prints an array, one object per diagnostic, with its code, severity, message, file, start and end, and its documentation `url`. Agents and scripts read this one.
- **`sarif`** prints a SARIF 2.1.0 log, which code-scanning tools in CI read.

A component that writes React's `className` gets this from `unframework check`, and an exit code of `1`:

```txt
error[UF3004]: `className` is written `class`: elements take HTML's attribute names, in lower case.
```

A usage error isn't a diagnostic, so it goes to standard error as plain text, whatever the format.

## explain

`explain` prints what a diagnostic code means and how to fix it, with the link to its section of [Diagnostics](/docs/reference/diagnostics):

```bash
unframework explain UF7005
```

```txt
UF7005 target-not-detected (error)
The bundler plugin could not detect a target

The bundler plugin has no `target` option, and none of the plugins in the Vite configuration
belongs to a framework it knows.

Add the framework's Vite plugin to the configuration, or pass `target` to the Unframework
plugin.

https://unframework.dev/diagnostics/UF7005
```

An unknown code exits `2`.

## init

`init` starts a project in the directory it runs in, and names each file it writes:

- **`unframework.config.ts`,** which names all seven targets, `src` and `dist`.
- **`src/Button.uf.tsx` and `src/Button.css`,** an example component and its stylesheet.
- **`tsconfig.uf.json`,** which type-checks your `.uf.tsx` and `.uf.ts` files against Unframework's JSX types: `tsc --noEmit -p tsconfig.uf.json`.
- **`AGENTS.md`,** which points agents at these docs and names the commands that check and build.

`check` passes on what `init` writes, with the info `UF4002` for Angular and Qwik, which every component with a stylesheet gets.

`init` adds no dependency, so add `typescript` to the project to run the type check. It doesn't edit your own `tsconfig.json` either. If you have one, add `**/*.uf.tsx` and `**/*.uf.ts` to its `exclude`, so your framework's JSX types don't check these files ([Type-checking in an app](/docs/tooling/bundler-plugin#type-checking-in-an-app) says why).

`init` never overwrites a file without `--force`. It exits `2`, names every file in the way, says what `--force` would do with each and writes nothing:

```txt
unframework init: In the way: AGENTS.md, src/Button.css, src/Button.uf.tsx, tsconfig.uf.json, unframework.config.ts. --force overwrites unframework.config.ts, src/Button.uf.tsx, src/Button.css, tsconfig.uf.json, AGENTS.md.
```

With `--force`, it overwrites those five files and leaves every other file alone. A `unframework.config.mts`, `.js` or `.mjs` also counts as in the way, because the new `.ts` file would quietly take its place: with `--force` it stays on disk, and `init` tells you that the `.ts` file takes precedence.

`init` writes no test file yet.

## test

`test` runs your project's tests on every target with Vitest: each case's spec in one browser project per target, and its server render in one project per target ([Testing](/docs/tooling/testing) shows how to write them). It runs your `vitest.config.ts` when there is one, and otherwise the configuration `defineTestConfig()` builds from `unframework.config.ts`. It takes three options:

- **`--target <t>`** tests one target, and can be repeated. The reference target joins every run: Vue when you test Vue, and otherwise your first target, unless you configure another.
- **`--update`** writes the shared expectations, `__expected__/`, which you then review. It's refused in CI.
- **`-- <vitest args>`** hands the rest to Vitest, like `-- --reporter=json` or a file filter.

It exits `0` when every test passes, `1` when one fails, and `2` on an unknown target, an invalid configuration or a package it needs that isn't installed. In that last case it names the packages to install: `@unframework.dev/testing`, `vitest`, `@vitest/browser-playwright` and `playwright`, then each target's framework and Vite plugin.

## visual

`visual` renders every example, a `*.example.uf.tsx` file with no props, on every target, and compares each target's geometry and pixels with the reference target's ([Visual parity](/docs/tooling/visual) shows how to write them). It takes four options:

- **`--target <t>`** runs one target, and can be repeated. The reference target joins every run.
- **`--live`** compares every target with the reference's capture in the same run, and is the default. **`--baseline`** compares with the baselines committed beside each example instead.
- **`--update`** writes those baselines. It's refused outside Unframework's baseline image.
- **`--out <dir>`** is the run directory, `.unframework/visual` by default. Each run writes `report.json` there, with an image of every capture and, for a target that differs, its diff, and `report.html`, a page that shows them.

It prints a line for each example, then the paths of `report.json` and `report.html`. It exits `0` when every example matches on every target, `1` when one differs or declares props ([UF7011](/docs/reference/diagnostics#UF7011)), and `2` on a usage or configuration error, or a package it needs that isn't installed: it names `@unframework.dev/visual` and the packages `test` needs.

## preview

`preview` shows every example and every component on every target side by side, in one page you keep open while you work ([Preview](/docs/tooling/preview) shows what it does). It starts one dev server per target and a page that frames them, prints that page's URL and each target's server, and runs until you press `Ctrl+C`. It takes two options:

- **`--target <t>`** shows one target, and can be repeated. By default it shows every target in your `unframework.config.ts`.
- **`--port <n>`** is the page's port. By default the system picks a free one, and each target's server always does.

It exits `0` once you stop it and every server has closed, and `2` on a usage or configuration error, a project with no example and no component, or a package it needs that isn't installed: it names `@unframework.dev/visual`, the packages `test` needs and `vite`.

`preview build` writes the same preview as a static site, which any static host serves at any path ([Build a static preview](/docs/tooling/preview#build-a-static-preview) shows what it writes). It builds each target's frame with Vite, prints any [UF7012](/docs/reference/diagnostics#UF7012) warning of your examples, then where it wrote the site and the targets it built, and exits `0`. It takes two options:

- **`--target <t>`** builds one target, and can be repeated. By default it builds every target in your `unframework.config.ts`.
- **`--out <dir>`** is the site's directory, `.unframework/preview` by default. The build empties it first, so it refuses your project's directory, a directory above it, and one that isn't empty and that no earlier build wrote.

It exits `2` on those refusals, a usage or configuration error, a project with nothing to show, a build that fails, or a package it needs that isn't installed.

## create-unframework

`create-unframework` starts a project in a new directory:

```bash
create-unframework my-components
```

It creates the directory if it has to and writes a private `package.json` that depends on `@uxfront/unframework`. Then it runs that project's own `unframework init`. It installs nothing itself, so when `@uxfront/unframework` isn't in the directory's `node_modules` yet, it stops after the `package.json`, exits `1` and tells you to install the dependencies and run `unframework init` there. It never overwrites an existing `package.json`.

[Installation](/docs/getting-started/installation#install-the-packages) says how to install the packages from npm.

The decision behind this page is [ADR-0076](https://github.com/uxfront-com/unframework/blob/main/docs/adrs/0076-configuration-and-the-cli.md).
