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

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 and 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:

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

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

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.

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 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

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

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.

Scripts and installed binaries

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

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.
• brix env types, run, and upload: schemas and secrets.
• brix openapi generate: specification-driven API contracts.
• brix contentful typegen and upload: Contentful models and applications.
• 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.
• brix release <bump>: confirm and dispatch a configured release.
• brix skills install: reconcile packaged guidance without reinstalling dependencies.

Git hooks and troubleshooting

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 for failing behavior.