Tools

brico CLI

Every command and flag of the single-binary engine that captures, versions, publishes and installs bricks.

Available

brico is one static Go binary. It needs no runtime. The only other tool it uses is git, for the Vault. Install it with the steps in Getting started.

bash

brico <command> [arguments] [flags]
brico --help                 # all commands
brico <command> --help       # one command in full
brico --version

Global flags

These work with every command.

Flag	Description
`--vault <path>`	Use this Vault instead of the configured one. Overrides BRICO_VAULT and ~/.brico/config.json.
`--cwd <dir>`	Run as if you were inside <dir>. Useful in scripts and monorepos.
`-h, --help`	Show help for the command.

Commands at a glance

Command	What it does
`extract`	Suggests modules in this project that are worth capturing
`capture`	Scans a module, writes its manifest and stores a version in the Vault
`list`	Lists every brick in the Vault
`search`	Searches the Vault by name, description or tag
`add`	Installs a brick into this project
`upgrade`	Moves installed bricks to newer Vault versions, without losing local edits
`remove`	Uninstalls a brick from this project
`doctor`	Checks the engine, adapters, Vault and project
`publish`	Pushes the Vault, or one brick, to a git repository
`pull` / `update`	Pulls the Vault from its repository
`diff`	Shows what changed in the local Vault
`ui`	Opens the terminal interface

Commands that change files ask for confirmation first. Pass -y to skip the prompt in scripts and CI.

brico extract

bash

brico extract

Analyses the current NestJS or Next.js project and lists directories that look like self-contained modules, ranked by confidence. Nothing is written. Use it to decide what to capture.

brico capture

bash

brico capture <name> [flags]

Scans a module directory, works out its npm dependencies (with versions from your package.json) and the environment variables it reads, writes a brico.manifest.json, and commits the snapshot to the Vault. Without --path, it uses the directory extract suggests for <name>, then src/<name>. With --path and no name, the name is the directory’s name.

Flag	Description
`-p, --path <dir>`	Directory to capture, relative to the project root.
`-d, --description <text>`	One-line description, used by search.
`-t, --tags <a,b,c>`	Comma-separated tags.
`--module-version <semver>`	Version to publish. Defaults to 0.1.0. An existing version is never overwritten.
`--visibility <public\|private>`	Defaults to defaultVisibility in the global config.
`-y, --yes`	Skip the confirmation prompt.

bash

brico capture auth -p src/auth -d "JWT auth with Passport" -t security,jwt
brico capture auth --module-version 0.2.0 -y        # publish a new version

Capture reports two problems before it writes anything:

NOT self-contained. Imports point outside the module, through an alias such as @/lib or an escaping ../../. Those files will not be copied, so the brick will not compile elsewhere. See R1 and R2.
Refusing to capture. Credential-shaped files such as .env, *.pem or .npmrc were found. The Vault is a git repository that gets pushed, so a captured secret would be a published secret. Template files like .env.example are allowed.

brico list

bash

brico list

Lists every brick in the Vault as a table: name, latest version, framework, tags and description.

brico search

bash

brico search <query>

Matches the query against brick names, descriptions and tags. Example: brico search jwt.

brico add

bash

brico add <name>[@version] [flags]

Resolves the version, checks that the brick’s framework matches this project, then:

copies the brick’s files to its install path;
records it in brico.json;
appends its required environment variables to .env.example;
prints the wiring steps for your framework.

Flag	Description
`--path <dir>`	Install somewhere other than the manifest or adapter default.
`-y, --yes`	Skip confirmation prompts, including the one for a non-empty target directory.
`--force`	Install even when no supported framework is detected. The framework check is skipped.

bash

brico add auth                 # latest
brico add auth@^0.2.0          # newest compatible
brico add auth --path src/modules/auth

brico upgrade

bash

brico upgrade [name][@version] [flags]

Moves each installed brick, or just name, to the latest version (or the given @version) in the Vault it came from. It compares your installed files with the Vault copy of the installed version, so it knows what you changed:

A brick with local edits is reported as dirty and skipped. With --force, the installed copy is first backed up next to itself as <path>.brico-backup-<timestamp>, then overwritten.
Files the new version drops are deleted only if you never changed them. Files you changed are kept and reported.
Files you added that the brick never listed are never touched.

Flag	Description
`--check`	Report available upgrades and their state; change nothing.
`-y, --yes`	Skip confirmation prompts.
`--force`	Upgrade dirty bricks too, after backing them up.

bash

brico upgrade --check          # what could move?
brico upgrade auth@0.3.0

brico remove

bash

brico remove <name> [-y]       # alias: brico rm

Prints the framework cleanup steps, deletes the brick’s install directory, and drops it from brico.json. The Vault is not touched.

brico doctor

bash

brico doctor

Runs a checklist and exits non-zero if any check fails, so it works as a CI step:

engine version and registered adapters;
framework detection and an adapter for it;
the Vault: it opens, its index loads, and the latest version of every brick is intact;
the project: brico.json parses, and every installed brick is present at its path.

brico publish

bash

brico publish [brick] [flags]

Pushes the whole Vault, or every version of one brick, to a git repository. The first time, it asks for your main repository and saves it as publishRepo in ~/.brico/config.json. Publishing one brick merges it into what the target repository already has and reconciles the index. Pushes use your existing git credentials.

Flag	Description
`--repo <url>`	Publish to this repository, without prompting.
`-l, --elsewhere`	Publish to a different repository; prompts for its URL.
`--branch <name>`	Remote branch to push to. Default main.
`-y, --yes`	Skip the confirmation prompt.

bash

brico publish                                   # whole Vault → main repo
brico publish auth                              # one brick, all versions
brico publish --repo git@github.com:acme/team-vault.git

brico pull and brico update

bash

brico pull [--repo <url>]
brico update                   # same as pull

Pulls the Vault from its configured repository (the main branch), or from --repo. If nothing is configured, run brico publish once or pass --repo.

brico diff

bash

brico diff

Shows the git status of the local Vault: what has changed since it was last published or pulled.

brico ui

bash

brico ui

Opens the full-screen terminal interface. See Terminal UI.

Not in the binary yet

brico create (new projects from templates) and brico mcp (the MCP server) are designed but not registered as commands. They will appear in brico --help once they produce real results.