Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / ReferenceRead Markdown
    On this page

    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
    
    • 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, discovered E2E suites, and an integrated Storybook catalog; a focused selection runs only the chosen boundary.
    • build creates production output. Libraries and workspace roots with a Storybook integration also build the static catalog. start serves a built Hono application, not a React SPA or library.
    • verify runs diagnosis, checks, tests, builds, and applicable Storybook gates without reinstalling dependencies. In CI, run brix ci first.

    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-local omits local and override files.
    • brix dev --no-env skips loading for a server that already receives a resolved environment. It cannot be combined with --stage or --no-local, and brix dev --env is rejected.
    • brix test loads nothing unless asked: --env selects the test-run stage and --stage <stage> another stage. --no-local requires one of them.
    • brix build loads nothing by default and has no implicit stage: --stage <stage> opts in, and --env is rejected so test-run values 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:

    package.json
    {
      "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, and build: component catalogs.
    • brix env types, run, export <stage> --target github, and upload: schemas and secrets.
    • brix openapi generate: specification-driven API contracts.
    • brix contentful typegen and upload: 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 -L with 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. --yes skips 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] and brix promote status: operate and inspect the persistent promotion controller, which listens on loopback unless --host is 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 generated promote.yml deploy 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; reads HOST (default 0.0.0.0), PORT (default 3000), optional BRIX_PUBLIC_ORIGIN, BRIX_KEEP_ALIVE_TIMEOUT_MS (default 65000), and BRIX_SHUTDOWN_TIMEOUT_MS (default 10000), and drains in-flight requests on SIGTERM/SIGINT. It refuses a build with serviceSignatures, which only its Lambda handler verifies. See Node deployment.
    • brix format, brix check, brix staged
    • brix 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 types
    • brix 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|deploy
    • brix promote serve --database <path> [--host 127.0.0.1] [--port 3000]
    • brix promote register --tag <vX.Y.Z> --yes
    • brix launcher update [--version stable|next|v<version>], brix launcher rollback