# CLI Compile a source tree into rewritten modules, CSS, source maps, and packed contracts. The `zyzz` binary compiles without a bundler or configuration file. Source imports provide configured authoring helpers, and downstream tooling lowers TypeScript and JSX. [Getting Started](/docs/introduction/getting-started?framework=cli) covers the setup. ```sh # Compiles src into dist once npx zyzz build ``` ## Signature ```sh # Compile once, or compile and watch zyzz build [src] [options] zyzz dev [src] [options] ``` Both commands accept the same argument and options. Paths resolve from the working directory. ## Commands ### build Compiles once and publishes the output. A missing source directory or compilation error exits with a nonzero status. ```sh # Compiles app into build npx zyzz build app --out-dir build ``` ### dev Compiles immediately, then rebuilds after changes within the source tree. A compilation error keeps the last successful output, and the next valid edit recovers. `Ctrl-C` and `SIGTERM` stop watching after pending output is published. ```sh # Rebuilds dist after each source change npx zyzz dev ``` ## Arguments ### src * **Type:** `string` * **Default:** `'src'` The authored JavaScript and TypeScript module tree. The output directory is excluded from discovery. ```sh # Compiles the app directory npx zyzz build app ``` ## Options ### --color-scheme * **Type:** `'light' | 'dark'` The scheme compiled into native output. It is required with `--target native` and rejected for web builds. ```sh # Compiles native tables with dark values npx zyzz build --target native --color-scheme dark ``` ### --css-only * **Type:** `boolean` * **Default:** `false` Emits CSS and CSS maps without transformed modules or packed contracts, plus the [initialization script](#output) when a configuration produces one. The original source runs as authored, so identity-bearing declarations need explicit identities. ```sh # Emits only stylesheets for source that runs uncompiled npx zyzz build --css-only ``` ### --external * **Type:** `readonly string[]` Imports left in emitted modules without resolution, matched by exact name or by a prefix ending in `*`. Repeat the flag for several patterns, and quote prefixes to prevent shell expansion. Externals cannot supply compiled styles or themes. ```sh # Leaves virtual icon imports to a downstream plugin npx zyzz build --external '~icons/*' --external framework-config ``` Any other unresolved bare import fails the build. ### --minify * **Type:** `boolean` * **Default:** `false` Minifies emitted CSS with Lightning CSS. Browser syntax is otherwise preserved without compatibility targets. ```sh # Emits minified stylesheets npx zyzz build --minify ``` ### --out-dir * **Type:** `string` * **Default:** `'dist'` The output directory, which has one active writer at a time. Cleanup removes only unchanged files that a previous build emitted, leaving unrelated files in place. ```sh # Writes output to build npx zyzz build --out-dir build ``` ### --package-id * **Type:** `string` * **Default:** `package.json` name, otherwise `'app'` The stable package identity that compiled module IDs, class names, and source maps derive from. It defaults to the `name` in the working directory's `package.json`. ```sh # Names compiled modules after the published package npx zyzz build --package-id my-library ``` ### --platform * **Type:** `'ios' | 'android'` The native platform for platform branches, required when styles author them. It is rejected for web builds. ```sh # Compiles iOS branches npx zyzz build --target native --color-scheme light --platform ios ``` ### --script * **Type:** `string` * **Default:** `'/zyzz.js'` The path of the initialization script. Outside the output directory, the CLI replaces only a file that starts with its `/* zyzz initialization */` comment, such as one in a public directory. ```sh # Writes the script where the dev server serves it npx zyzz dev --script public/zyzz.js ``` ### --target * **Type:** `'web' | 'native'` * **Default:** `'web'` The compilation target. See [React Native](#react-native) for native output. ```sh # Compiles native modules instead of CSS npx zyzz build --target native --color-scheme light ``` ## Output For `src/button.ts`, the CLI emits `dist/button.ts` with its source map, `button.ts.css` with its map, and the packed `button.ts.zyzz.json` contract. Global contributions also produce `zyzz.shared.css`. The complete `zyzz.css` holds shared contributions, then every module stylesheet with dependencies first. ```html title="index.html" ``` Applications load `zyzz.css`, and libraries can publish the per-module files beside their modules. A configuration whose module uses `appearance`, `script`, or `vars` also produces `zyzz.js`, a classic script for the start of the `` that restores the saved variable set and color scheme. ## Structured Output `--json` prints the build result with its `changed` and `files` lists. `zyzz dev --format jsonl` streams one event per rebuild, with `status: 'built'` and those lists, or `status: 'error'` and a message. ```sh # Streams build and error events as JSON lines npx zyzz dev --format jsonl ``` ## Errors A build fails when the source directory is missing, when an option conflicts with the target, or when compilation fails. The message names the source location where one applies. ```sh # Rejected because --platform requires --target native npx zyzz build --platform ios ``` Bare imports resolve from `node_modules` with the `node` and `import` conditions. Installed packages supply compiled styles through adjacent `.zyzz.json` contracts, and an import that resolves to no file fails the build unless it is marked [external](#--external). ## React Native `--target native` emits modules, maps, and packed contracts without CSS or an initialization script, so `--css-only` and `--script` are rejected. The color scheme and platform stay fixed for a watch session. ```sh # Watches and compiles dark Android tables npx zyzz dev --target native --color-scheme dark --platform android ```