> [Agent navigation index](/llms.txt)

# CLI Reference

Use the project-pinned `brix` command for application and library workflows. Brix owns compatible tool versions, generated state, framework boundaries, and workspace selection. Do not invoke the underlying build, lint, test, or package-management tools directly.

## Create or adopt a project

```sh
brix create app storefront
brix create react-app admin
brix create contentful-app editorial
brix create library contracts
brix create ui-library components
brix create workspace commerce

```

Create the project kind that matches its runtime. A library exposes `src/index.ts` and builds typed ESM through the managed library build. A UI library adds ordinary Preact components and colocated stories. React applications are browser-only; full-stack applications own Hono routes and Preact islands. See [React](/docs/react) and [workspaces](/docs/workspaces).

Creation follows the launcher's stable selector by default and resolves it to an immutable Git tag. Use `--version next` only for deliberate prerelease evaluation. Inside a workspace, new members inherit the workspace version; omit the selector there. Bare application names go under `apps/`, and library names under `packages/`.

To adopt existing code, start with a clean tree and inspect the plan:

```sh
brix init --dry-run
brix init
brix doctor

```

Initialization creates missing canonical files and merges supported configuration; it does not overwrite arbitrary custom executable configs. For independently managed workspace applications, use `brix workspace adopt`, not application initialization.

## Install and inspect

```sh
brix install
brix doctor
brix doctor --json
brix inspect routes --json
brix inspect islands --json
brix inspect config --json
brix inspect assets --json
brix inspect workspace --json

```

After pulling a changed framework declaration or lockfile, run `brix install` before other workflows. It installs the declared version and reconciles generated state and skills. It does not choose a newer framework release.

Doctor checks project shape, import/export boundaries, exact dependency ownership, generated environment types, and workspace consistency. Inspection exposes discovered routes, hydration priorities, build assets, and project configuration. JSON output uses a versioned envelope; preserve nonzero exit status and reject unknown schema versions in automation.
Config and asset inspection resolve custom Vite config/output and support application, React, and
library project kinds. JSON-mode failures use the versioned envelope with an error code and message.

## Daily lifecycle

```sh
brix dev
brix format
brix check
brix test
brix build
brix start
brix ci
brix verify

```

- `dev` runs the application development server or watches a library build.
- `format` writes formatting changes. `check` verifies formatting, lint, types, and structure without tests.
- `test` runs Vitest and discovered E2E suites; focused selection runs only the chosen boundary.
- `build` creates production output. `start` serves a built Hono application, not a React SPA or library.
- `ci` performs a clean, lockfile-exact installation.
- `verify` runs diagnosis, checks, tests, builds, and applicable Storybook gates without reinstalling dependencies.

Development loads the authored Varlock environment by default. Build and test are provider-free unless selected with `--env` or `--stage`; see [environment configuration](/docs/environment).

## Built-in linting

Normal `brix check` applies the managed Oxfmt and Oxlint baseline, type-aware and architectural
rules, and the version-pinned Brix lint plugin. No separate tool or plugin installation is needed.
See [linting and formatting](/docs/linting-formatting) for defaults, exceptions, native config,
workspace-root ownership, and editor behavior.

\<span id="keep-known-types-and-visible-input-boundaries">\</span>
\<span id="prefer-typed-property-access-and-calls">\</span>
\<span id="test-behavior-without-replacing-modules">\</span>
\<span id="explain-necessary-exceptions-locally">\</span>
\<span id="configure-project-policy">\</span>

## Generate feature slices

```sh
brix add api fetchBooking --feature booking
brix add page bookingDetails --feature booking
brix add fragment siteHeader --feature chrome
brix add island BookingActions --feature booking
brix add store booking --feature booking

```

Generators require an application and `--feature`. API/page/store names use camelCase; island component names use PascalCase. Generated files follow discovery conventions and refuse existing targets before writing. Implement the generated behavior and test together.

Ordinary shared components belong in libraries. Islands and cross-island store declarations belong to the consuming application because its build assigns their identities.

## Dependencies and upgrades

```sh
brix deps add date-fns
brix deps why date-fns
brix deps remove date-fns
brix deps update --latest --dry-run --json
brix upgrade --dry-run --json

```

Dependency commands write exact declarations. Do not independently add Hono, Preact, Zod, Panda, or Brix-owned tooling; use their supported facades. Managed React dependencies are written by Brix's React integration.

Review the complete change plan before applying dependency updates or framework upgrades. The launcher can be updated or rolled back separately with `brix launcher update` and `brix launcher rollback`; this does not upgrade a project's pin. See [dependency and Brix upgrades](/docs/releases-upgrades).

## Scripts and installed binaries

```sh
brix run generate-report
brix run scripts/report.ts
brix watch scripts/report.ts
brix exec some-installed-binary
brix dlx some-temporary-package

```

`run` executes a package script or local JS/TS file. `watch` restarts a local file as its dependencies change. `exec` invokes an installed binary; `dlx` explicitly downloads a temporary package. The example names are application-owned, not built-in commands. Environment selection for scripts is explicit through `brix env run <stage> -- <command>`.

## Workspace targeting

```sh
brix dev#storefront
brix check#apps/storefront
brix test apps/storefront/e2e/checkout.spec.ts
brix workspace link apps/storefront packages/contracts
brix workspace adopt apps/legacy --dry-run
brix workspace integrate react apps/legacy --dry-run

```

Select by unique basename, package name, or path. Root installation and verification remain workspace-wide. External members keep their own runtime and scripts; Brix coordinates the phases they expose.

## Specialized workflows

- `brix storybook init`, `dev`, `test`, and `build`: [component catalogs](/docs/storybook).
- `brix env types`, `run`, and `upload`: [schemas and secrets](/docs/environment).
- `brix openapi generate`: [specification-driven API contracts](/docs/openapi).
- `brix contentful typegen` and `upload`: [Contentful models and applications](/docs/contentful).
- `brix msw init public --save`: browser worker setup for HTTP-consuming tests.
- `brix playwright install chromium`: offline browser provisioning or repair, not routine setup.
- `brix release init --repository <owner/repository>`: scaffold configured [application or library releases](/docs/releases-publishing).
- `brix release <bump>`: confirm and dispatch a configured release.
- `brix skills install`: reconcile packaged guidance without reinstalling dependencies.

## Git hooks and troubleshooting

```sh
brix hooks status
brix hooks enable
brix hooks disable
brix staged

```

Hook policy lives in `.brix-hooks/`; generated dispatchers are clone-local. Brix does not replace another tool's `core.hooksPath`. `brix staged` verifies the exact Git index snapshot without mutating unstaged edits. Fix formatting with `brix format`, stage the intended changes, and rerun checks. CI remains authoritative even when hooks are disabled.

When a workflow fails, address the first diagnostic rather than bypassing it with another toolchain. Begin with `brix doctor --json`; inspect routes/islands when discovery is wrong, check the environment schema when generated types are stale, and use the focused commands in [testing](/docs/testing) for failing behavior.