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.
For an existing checkout, the recommended first run is brix install, then brix doctor. For a
new feature, use the narrow lifecycle command while iterating and finish with brix verify. The
task-oriented sections below explain when to use each command; the
command reference at the end lists every command and flag.
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.
Pass --version next only for deliberate prerelease evaluation, or --version v<version> for an
exact release; the selected release becomes the global CLI, but later creations follow the
persisted selector again. Inside a workspace, new members inherit the workspace version; omit the
selector there. Bare application names go under apps/, and library names under packages/.
brix create <kind> . (for example brix create app .) populates an existing empty directory in
place; a non-empty destination is refused before Brix snapshots anything, and a failed creation
removes the directories it created, including new parent directories such as a workspace's first
apps/.
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, skills, and Git hook dispatchers. It does not choose a newer framework release. A current lockfile is installed exactly, including on a clean checkout. Outside CI, only changed manifest declarations are resolved again; in CI, a stale lockfile fails the install. Use brix deps or brix upgrade to change locked versions.
brix ci is the CI counterpart and runs only at a standalone project or workspace root. It installs
the lockfile exactly (a stale lockfile fails), reconciles project-pinned skills, and checks that
every application's committed src/env.generated.d.ts matches its environment schema, failing
rather than rewriting stale types. It does not configure Git hooks.
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. Route and island inspection read the same production src/ sources as the build, so tests, stories, and modules outside src/ never appear. JSON output uses a versioned envelope; preserve nonzero exit status and reject unknown schema versions in automation.
Managed lifecycle scripts must execute one direct brix <command> invocation, with optional
ordinary arguments, environment assignments, env, exec, and Brix's --verbose prefix.
Use prefixes in the order NAME=value exec env NAME=value brix --verbose <command>, omitting
any you do not need. Arguments may use literal single or double quotes, including
--outDir="build output"; shell expansion and backslash escapes are outside this grammar.
For example, BRIX_VERBOSE=1 brix build --mode production is supported. Shell control flow,
pipes, multiple command lines, command substitution, and arbitrary wrapper executables are not accepted as delegation;
echo brix build or false && brix build do not satisfy the lifecycle contract. Move custom
orchestration into a separately named script and retain the canonical lifecycle script.
Other package scripts must not invoke Node or a package runner directly. Doctor rejects a script command that starts with node, tsx, ts-node, npx, pnpx, or bunx (after any assignments, env, exec, or cross-env), including node or tsx run through brix exec or brix dlx, anywhere in a chain such as brix build && node scripts/post.mjs. Use brix run <file> for files and brix exec <binary> for installed binaries; when the script is a single file invocation, the repair gives the exact replacement, such as brix run scripts/seed.mjs for a script that ran node scripts/seed.mjs. Installation hooks (preinstall, install, postinstall, and prepare) are exempt because they run while dependencies are being installed. Doctor reads separators and quotes but not substitutions, so a runner inside $(...) is not detected.
Runtime facade checks follow the application kind. React applications use @brix/react, not
Preact-backed brix/hooks, brix/preact (including subpaths), brix/signals, brix/islands
(including subpaths), brix/contentful/rendering (including subpaths), or brix/test/browser;
React browser tests import render, page, and userEvent from @brix/react/test. Browser-only
React applications also reject server-only brix/server, brix/contentful/server, brix/hono
(including subpaths), brix/lambda, brix/cache/dynamodb, and brix/cache/fastly, and the
Preact-managed brix/panda and brix/storybook (including subpaths). Preact applications must not
import runtime bindings from @brix/react. These checks include re-exports and statically known
dynamic imports; type-only imports and exports remain allowed. Framework-owned packages such as
react and react-dom are rejected even in type-only imports; React applications use
@brix/react, @brix/react/client, and @brix/react/dom instead. Libraries are not assigned an
application runtime.
Route layout, route and contract export names, fragment, Page.tsx, "use island", and
*.store.* checks mirror Preact application discovery, so doctor applies them only to
brix.project: "application". A React application or library can name its own modules
route.tsx or cart.store.ts. Libraries cannot declare "use island" modules or *.store.*
modules that export a createStore tuple, because each consuming application owns those
identities. Doctor rejects a file: Brix dependency; set BRIX_ALLOW_LOCAL_DEPENDENCY=1 only to
verify a local Brix candidate.
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.
A failure keeps the schemaVersion and kind of that command's success envelope: upgrade-plan
(schema 1) for brix upgrade --dry-run --json and dependency-upgrade-plan (schema 2) for
brix deps update --dry-run --json. brix deps why --json prints the package engine's own JSON
without a Brix envelope. A malformed package.json in brix doctor --json is reported as the
valid package manifest is required diagnostic.
Malformed package/asset JSON reports INVALID_JSON with the filename. Invalid manifest shapes or
consumed configuration fields report INVALID_INSPECTION_DATA, with the file and relevant field
path, such as package.json#dependencies.brix. Fix that input and retry; automation should use the
error code rather than depend on exact diagnostic wording. Unconsumed metadata remains tolerated.
Asset inspection returns unique, sorted paths, so CSS shared by several application entries appears only once. It continues to ignore malformed asset entries and non-string file/CSS values.
Daily lifecycle
#brix dev
brix format
brix check
brix test
brix build
brix start
brix verify
devruns the application development server or watches a library build.formatwrites formatting changes.checkverifies formatting, lint, types, and structure without tests.testruns Vitest, discovered E2E suites, and an integrated Storybook catalog; a focused selection runs only the chosen boundary.buildcreates production output. Libraries and workspace roots with a Storybook integration also build the static catalog.startserves a built Hono application, not a React SPA or library.verifyruns diagnosis, checks, tests, builds, and applicable Storybook gates without reinstalling dependencies. In CI, runbrix cifirst.
At a workspace root, formatting, checking, and verification include ordinary root-owned files as
well as member projects. Running a plain lifecycle command inside a member has the same shared-library
preparation as command#member; external member commands, including watch, stay scoped to that member.
Focused library build and dev refresh transitive upstream library exports before building or
watching the selected library. Upstream libraries build once, not as additional watchers; see
workspace workflows.
Platform and environment flags
#Full-stack applications build for the platform in vite.config.ts (node by default).
brix dev --platform <platform> and brix build --platform <platform> override it for one command,
choosing from node, lambda, cloudflare, and fastly. The flag requires a full-stack
application; from a workspace root, select the member, as in brix build#storefront --platform lambda.
See deployment builds.
Full-stack application development loads the authored Varlock environment for the development stage by default, including local and override files:
brix dev --stage <stage>selects another stage;--no-localomits local and override files.brix dev --no-envskips loading for a server that already receives a resolved environment. It cannot be combined with--stageor--no-local, andbrix dev --envis rejected.brix testloads nothing unless asked:--envselects thetest-runstage and--stage <stage>another stage.--no-localrequires one of them.brix buildloads nothing by default and has no implicit stage:--stage <stage>opts in, and--envis rejected sotest-runvalues cannot reach a deployable build.
Managed full-stack E2E loads its test-run server environment when none was inherited, so keep
that stage provider-free for offline runs; see environment configuration and
E2E tests. Library dev and build do not load environment providers and
reject Brix environment options (--env, --stage, --no-env, --no-local). Environment options
are also rejected inside brix env run, which has already resolved the environment. Arguments after
-- belong to the underlying tool and are not interpreted as Brix environment options.
In full-stack Vite development, adding an invalid route or island reports validation errors in the terminal and browser error overlay without stopping the watcher. Correct or remove the file to retry without restarting. Discovery retains its last valid catalogue, but requests importing invalid source may still fail. Invalid source at startup or during a production build still fails validation. Fastly uses its separate rebuild-and-restart development loop.
Node and generated HTTP Lambda builds initialize the built application in a separate process before success, rejecting assembled route conflicts before deployment packaging. This runs authored module-level code but does not dispatch requests or load Brix's request-time environment providers. Keep provider access inside request handlers. Cloudflare builds do not perform this initialization check; validate the assembled worker in its deployment runtime. Fastly retains its native compilation step rather than importing its worker artifact in Node.
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.
Generate feature slices
#brix add api fetchBooking --feature booking
brix add response downloadReport --feature reports
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/response/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.
Generators also check required named project bindings before writing; restore the reported export
in your existing setup rather than replacing its configuration. Obvious literal GET URL collisions
with conventional contracts fail before writing, including the same action name in another feature.
Fragment generation also fails when another feature's createFragment uses the same literal name,
because every fragment is served at /_brix/fragments/<name>. This static check does not evaluate
computed paths, computed fragment names, or custom contract factories.
Keep route directories flat when moving a slice. Doctor and discovery reject misplaced feature
route.ts modules with a supported destination. A route-harness test mounts the supplied route;
passing it alone does not prove that production discovers the file.
If a write fails, the generator removes files it created, including partial writes. It leaves directories and existing files alone. Cleanup failures are reported with the original error; inspect remaining files before retrying.
Do not run generation concurrently with edits to the same target paths. Rollback checks file identity before removal, but that check and removal are not atomic.
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. Brix checks the manifests after deps add, so Git, tarball, file, or alias specifiers cannot introduce those packages either. Managed React dependencies are written by Brix's React integration. Run from any directory in a project: Brix targets the nearest package.json and rebases relative path specifiers to it. brix deps why <package> --json passes JSON output through from the package engine. At a workspace root, deps update covers every member; see workspace dependencies.
Among dependency commands, only deps update accepts --dry-run; deps add and remove apply
immediately. For both deps update and upgrade, --json requires --dry-run: a structured plan
is a preview, never an applied change. deps update rejects --no-save; use --dry-run for a
preview that restores the prior state. A real brix upgrade
requires a clean, committed Git tree; dry runs work anywhere.
Review the complete change plan before applying dependency updates or framework upgrades. brix upgrade updates both the global CLI and the current project or workspace pin. The launcher alone can be updated or rolled back with brix launcher update [--version <selector>] and brix launcher rollback; this does not change a project's pin. Only launcher update --version changes the selector that later refreshes follow; upgrade --version and create --version are one-off selections. After launcher rollback, create and init skip automatic refreshes until an explicit update. See installation and 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
brix env run staging -- run scripts/report.ts
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.
Brix provides Node, so a project never needs node, npx, tsx, or ts-node. brix run <file> executes a local .ts, .tsx, .mts, .cts, .js, .jsx, .mjs, or .cjs file directly on the Brix-managed Node runtime, with no build step, loader flag, or extra dependency. Installed packages, brix/* facades, and the project's #/... imports resolve as they do in application code, and arguments after the file go to the script. When a package script and a file share a name, the package script runs.
Write scripts and one-off checks as TypeScript rather than .mjs helpers or node -e snippets, and have package scripts call Brix rather than Node:
{
"scripts": {
"seed": "brix run scripts/seed.ts"
}
}
Coding agents follow the same rule: the generated AGENTS.md and the packaged skills tell them to use brix run instead of invoking Node. brix doctor rejects package scripts that call node, tsx, ts-node, or npx directly; see install and inspect.
Scripts receive an application environment only when you select one explicitly with
brix env run <stage> [--no-local] -- <brix-command> [arguments...]. Everything after -- is a Brix
command without the brix prefix, such as run scripts/report.ts or start; arbitrary
executables, nested env commands, and #member selectors are rejected before any provider
resolves; run other programs through exec <binary>. brix env upload likewise validates
--account, --region, and --request-token before resolving secrets. Run it from the
application directory.
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 link apps/storefront packages/test-support --dev
brix workspace adopt apps/legacy --dry-run
brix workspace integrate react apps/legacy --dry-run
Select by unique basename, package name, or path with <command>#<member>. Installation and verification remain workspace-wide: brix install installs the whole workspace even from a member directory, while brix ci and brix verify must run at the workspace root and reject member selectors. workspace link --dev records a build- or test-only dependency. External members keep their own runtime and scripts; Brix coordinates the phases they expose.
Specialized workflows
#brix storybook init,dev,test, andbuild: component catalogs.brix env types,run,export <stage> --target github, andupload: schemas and secrets.brix openapi generate: specification-driven API contracts.brix contentful typegenandupload: Contentful models and applications.brix sign-request --purpose <owner/name> --key-stdin <url>: print a curl config that signs one request to a service that verifies service signatures. Never pass curl-Lwith it.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, or upgrade an unmodified Brix-generated workflow in place.brix release <bump> [--project <project>...] [--yes|-y]: review, confirm, and dispatch a configured release.--yesskips the default-No prompt for automation; a noninteractive run without it fails.brix release preview --local [--dry-run|--yes]: verify locally and push only an immutable branch-preview tag. Publishing requires--yes.brix promote init: migrate an untouched generated release workflow (Brix 2.1 or later) to configured Slack-approved promotion.brix promote serve --database <path> [--host 127.0.0.1] [--port 3000]andbrix promote status: operate and inspect the persistent promotion controller, which listens on loopback unless--hostis given; see hosting and credentials.brix promote register --tag v1.2.3 --yes: recover registration of an already-published candidate after verifying its publication; requires the administrative controller token. See promotion recovery.brix promote deploy: runs your deploy and verify commands inside the generatedpromote.ymldeploy job. It refuses to run outside GitHub Actions for the configured repository; do not invoke it manually.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, including one set in global or system Git configuration, and brix hooks enable refuses while executable hooks in .git/hooks (for example Git LFS hooks) would be shadowed; move that behavior into committed .brix-hooks/ policy, such as git lfs pre-push "$@" in .brix-hooks/pre-push, then remove the old hooks. When dispatch is enabled, brix install and brix init report a hooks conflict as a warning instead of failing. brix hooks status lists shadowed and foreign hooks, and brix hooks disable removes only Brix-generated dispatchers. Dispatchers keep your PATH first and append standard system directories only as a fallback. 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.
brix help <command> prints any command's usage without loading or installing its toolchain.
--help or -h after a command does the same for commands that Brix parses itself. Commands that
hand their arguments to a script, server, or tool (run, watch, exec, dlx, env, dev,
start, msw, and playwright) do not intercept --help: brix dev --help reaches the
development server's own option parser, and brix start --help fails with its usage error. Use
brix help <command> for those.
Timed lifecycle commands keep successful subprocess output quiet; a failure prints a diagnostic tail
and private log path. Use brix --verbose <command> for live output when the tail is insufficient,
and review logs for secrets before sharing them. Arguments after --, or after a run/exec
target, belong to the underlying tool rather than Brix.
Forwarded tool failures preserve ordinary child exit statuses, including through timed progress
and the spawn fallback when process replacement is unavailable. Brix validation and startup
failures still exit 1. On POSIX, managed tool and timed-task cancellation preserves SIGINT and
SIGTERM as signals rather than changing them to exit 1. The spawn path continues to interpret
status 130 as interruption. A timed task remains cancelled even if its child handles the signal
and exits zero; Brix waits for the captured child streams to close before finishing. Transactional
commands (deps, workspace, storybook init, init, create, and upgrade) defer the
interruption until they have restored the previous manifests, lockfile, and installed state, then
exit by the same signal. brix watch restarts once per change and exits by the interrupting signal.
This is not a universal error-code contract: the explicit Varlock environment wrapper still
reports ordinary command failures as exit 1.
Command reference
#Global usage is brix [--verbose] <command>[#<workspace-project>] [arguments...]. brix --version
prints the installed version, and brix help lists every command.
Project setup and inspection:
brix create app|react-app|contentful-app|library|ui-library|workspace <directory> [--version stable|next|v<version>]brix init [--dry-run]brix install [arguments...]: installs the whole workspace; uses the project pin without changing the global CLI.brix ci: standalone project or workspace root only.brix doctor [--json]brix inspect routes|islands|config|assets|workspace [--json]brix skills install
Lifecycle:
brix dev [--platform node|lambda|cloudflare|fastly] [--stage <stage>] [--no-local] [--no-env] [arguments...]brix build [--platform node|lambda|cloudflare|fastly] [--stage <stage>] [--no-local] [arguments...]brix test [--env | --stage <stage>] [--no-local] [arguments...]brix start: from a built full-stack application; readsHOST(default0.0.0.0),PORT(default3000), optionalBRIX_PUBLIC_ORIGIN,BRIX_KEEP_ALIVE_TIMEOUT_MS(default65000), andBRIX_SHUTDOWN_TIMEOUT_MS(default10000), and drains in-flight requests onSIGTERM/SIGINT. It refuses a build withserviceSignatures, which only its Lambda handler verifies. See Node deployment.brix format,brix check,brix stagedbrix verify: standalone project or workspace root only.brix hooks enable|disable|status
Features, dependencies, and workspaces:
brix add api|response|fragment|page|island|store <name> --feature <feature>brix deps add|remove|why [arguments...]brix deps update [packages...] [arguments...] [--dry-run] [--json]brix upgrade [--dry-run] [--json] [--version stable|next|v<version>]brix workspace adopt <path|package> [--dry-run]brix workspace link <consumer> <dependency> [--dev] [--dry-run]brix workspace integrate react <path|package> [--dry-run]
Scripts and tools:
brix run <package-script-or-file> [arguments...]brix watch <file> [arguments...]brix exec|dlx <command> [arguments...]brix msw <arguments...>,brix playwright <arguments...>brix sign-request --purpose <purpose> (--key-file <path> | --key-stdin) [-X <method>] [--data-binary @file|<string>] [-H 'Name: value']... [--sign-header <name>]... [--nonce <n>] <url>,brix sign-request --new-key
Integrations:
brix storybook init [--dry-run],brix storybook dev|build|test [arguments...]brix env run <stage> [--no-local] -- <brix-command> [arguments...]brix env export <stage> --target github [--allow-override <key>]brix env upload <stage> --account <id> --region <region> [--request-token <token>] [--endpoint-url <loopback-url>] [--allow-override <key>] [--json]brix env typesbrix openapi generate [<file-or-url> --out <directory> --name <name> | --config <path>] [--group-by tag|none] [--strict] [--dry-run|--check]brix contentful upload [arguments...]brix contentful typegen --space <id> --out <path> [--environment <id>] [--host <host>]
Releases and the global CLI:
brix release init --repository <owner/repository>brix release <major|minor|patch|stable|next [major|minor|patch]> [--project <project>...] [--yes|-y]brix release preview --local [--dry-run|--yes]brix promote init|status|deploybrix promote serve --database <path> [--host 127.0.0.1] [--port 3000]brix promote register --tag <vX.Y.Z> --yesbrix launcher update [--version stable|next|v<version>],brix launcher rollback