command-reference.md

Command Reference

This document defines the intended CLI surface for bricks. The conceptual model behind these commands lives in product-model.md; terms appear in glossary.md.

The command language is source-oriented. A consumer adds a source, pulls it, installs source projects from it, and later merges source changes into installed bricks.

First-Use Flow

bricks init
bricks source add talent-platform git@github.com:recruitment-co/talent-platform.git --pull
bricks source projects talent-platform
bricks install talent-platform/job-board-app --with-dependent-libs
bricks merge job-board-app

The first-use flow starts from an existing Git-backed Nx repo. source add --pull makes the whole source repo available under .bricks/sources, then install copies selected source into the consumer workspace.

Only pull sources you trust. Pulling installs the source repo's dependencies and evaluates its Nx project graph, so source-controlled lifecycle scripts and Nx plugins can execute locally.

Conventions

• Commands run from the root of a consumer Nx workspace unless stated otherwise.
• Workspace metadata lives at .bricks/config.json.
• Source repos are cloned or updated under .bricks/sources/<name>.
• .bricks/config.json is committed portable metadata; local cache paths are derived and are not written into config.
• Human-readable output is the default.
• Human-readable command runs use phase-level task progress so long Git, package-manager, Nx, copy, merge, and metadata steps are visible.
• Commands used by AI agents and scripts should support --json.
• --json and --quiet suppress task progress and interactive prompts.
• Mutating commands should support --dry-run and report planned file, metadata, Git, Nx, and package-manager changes without writing them.
• Conflicts should be normal Git conflicts in the copied source files.

Reference Format

Source project references use:

<source>/<project>[@ref]

Examples:

bricks install talent-platform/job-board-app
bricks install talent-platform/job-offer-ui@main

<source> is the local source name from .bricks/config.json. <project> is an Nx project discovered in the pulled source repo. @ref is optional and defaults to the source's configured ref.

Global Flags

Flag	Applies To	Behavior
--json	All commands	Print machine-readable output.
--dry-run	Mutating commands	Report the plan without writing changes.
--quiet	All commands	Suppress non-essential human output.
--verbose	All commands	Include diagnostic details in human or JSON output.
--help	All commands	Print command usage.

bricks init

Initialize Bricks metadata in the current consumer Nx workspace.

Synopsis

bricks init [--json] [--dry-run]

Behavior

1. Verify the current directory is the root of an Nx workspace.
2. Create .bricks/.
3. Create .bricks/config.json.
4. Initialize empty source and installed-brick records.

Writes

• .bricks/config.json

bricks source add <name> <git-url>

Register a Git-backed Nx repo as a source and make it available for pulling.

Synopsis

bricks source add <name> <git-url> [--ref <ref>] [--pull] [--json] [--dry-run]

Arguments

Argument	Meaning
<name>	Local source name used in source project references.
<git-url>	Git URL or local path for a repo containing an Nx workspace.

Relative local paths are resolved from the consumer workspace root before they are written to .bricks/config.json or cloned into .bricks/sources.

Flags

Flag	Behavior
--ref <ref>	Default ref used when a command omits @ref.
--pull	Pull immediately after registering the source.

Behavior

1. Validate <name> and <git-url>.
2. Write the source record to .bricks/config.json.
3. If --pull is present, pull the source immediately.

Writes

• .bricks/config.json
• .bricks/sources/<name> when --pull is present

bricks source pull [name]

Clone or update source repos under .bricks/sources.

This is a trusted-source operation. It installs dependencies from the pulled repo and evaluates the repo's Nx project graph.

Synopsis

bricks source pull [name] [--ref <ref>] [--json] [--dry-run]

Behavior

1. Resolve one source or all configured sources.
2. Clone the source repo when .bricks/sources/<name> does not exist.
3. Fetch and checkout the requested ref when the source already exists.
4. Verify the pulled repo is an Nx workspace.
5. Install the pulled source repo dependencies inside .bricks/sources/<name>.
6. Build the source Nx project graph.
7. Detect:
   • apps,
   • libraries,
   • project-to-project dependencies,
   • package dependencies,
   • dev dependencies needed for build, test, lint, or tooling.
8. Store analysis metadata for later install, status, diff, and merge commands.

--ref chooses the ref to pull for this operation. It records the pulled ref and commit but does not replace the source's configured default ref.

Writes

• .bricks/sources/<name>
• .bricks/config.json source analysis metadata

Non-Goals

This command does not copy source into the consumer workspace. It only makes the full source repo locally available for analysis and later install.

bricks source list

List configured sources and their latest pulled commit.

Synopsis

bricks source list [--json]

Output

The human output should show source name, repo URL, default ref, last pulled ref, pulled commit, and whether the local source cache is present.

bricks source projects <name>

List installable Nx projects discovered in a pulled source.

Synopsis

bricks source projects <name> [--json]

Output

The human output should show project name, project type, source path, package dependencies, dev dependencies, Nx tooling requirements, and dependent Nx libraries.

bricks source remove <name>

Remove a configured source and its local cache.

Synopsis

bricks source remove <name> [--force] [--json] [--dry-run]

Behavior

1. Refuse to remove a source that still has installed bricks unless --force is present.
2. Remove the source record from .bricks/config.json.
3. Remove .bricks/sources/<name>.
4. With --force, also remove install records that point at the source. Copied source files in the consumer workspace are not deleted.

bricks install [<source>/<project>[@ref]]

Copy source from a pulled source repo into the consumer workspace.

Synopsis

bricks install [<source>/<project>[@ref]] \
  [--as <alias>] \
  [--target <path>] \
  [--with-dependent-libs] \
  [--no-package-install] \
  [--no-nx-add] \
  [--json] [--dry-run]

Flags

Flag	Behavior
--as <alias>	Local installed-brick name. Defaults to the source project name.
--target <path>	Consumer workspace path for the copied source.
--with-dependent-libs	Also install Nx libraries required by the selected project.
--no-package-install	Do not add detected package dependencies automatically.
--no-nx-add	Do not initialize detected Nx tooling packages automatically.
--keep-partial	Keep copied files/package edits when a failure occurs.

Behavior

1. Resolve the source project reference.
2. In interactive human mode, when no reference is provided, prompt for a configured source and then one uninstalled project from that source.
3. If the selected source has missing or stale analysis, prompt before pulling and analyzing it.
4. In --json, --quiet, or non-interactive mode, require an explicit <source>/<project>[@ref].
5. Ensure the source is configured.
6. Pull the source if the required ref is not available locally.
7. Resolve <project> in the source Nx project graph.
8. Read package dependencies and dev dependencies from each copied project's local package.json.
9. Extract tooling package providers from resolved target executors and syncGenerators.
10. Initialize missing tooling packages with nx add unless --no-nx-add is present.
11. Report dependent Nx libraries.
12. Filter package names supplied by copied source projects.
13. Add the remaining package dependencies unless --no-package-install is present.
14. Copy the selected project into the consumer workspace.
15. If --with-dependent-libs is present, copy required source libraries too.
16. Refresh package-manager workspace links after copied manifests exist.
17. Copy tracked workspace helpers imported by copied root-level project configs, preserving conflicting consumer files.
18. Merge TypeScript aliases for copied projects into tsconfig.base.json.
19. Update Nx metadata so copied projects are visible to the consumer workspace.
20. Record project-specific dependency metadata in .bricks/config.json.

Interactive prompts are rendered through Listr task prompts, not standalone terminal prompts, so selection UIs do not fight the active progress renderer.

<projectRoot>/package.json is authoritative for package requirements. Runtime requirements come from dependencies, peerDependencies, and optionalDependencies; local build and test requirements come from devDependencies. A source project without a local manifest contributes an empty package contract.

Resolved target executors and syncGenerators contribute Nx tooling package requirements. Bricks routes missing tooling packages through nx add <package> --updatePackageScripts=true before copying source. These initializers may update workspace configuration and are durable preparation: failed initializers produce nx-add-failed warnings while remaining tooling packages continue to run.

The workspace refresh runs after copying even with --no-package-install. It does not add detected external requirements, but it lets package managers link copied workspace packages declared through their local manifests.

If the consumer workspace already declares a package with a range that does not overlap the source requirement, Bricks keeps the consumer range, skips adding that package, and records a dependency-range-conflict-kept-existing warning. Other missing, non-conflicting package dependencies are still installed.

Supported Install Shapes

• Copy an app.
• Copy a library.
• Copy a project plus its dependent Nx libraries.

bricks merge [alias]

Update installed bricks by merging newer source commits into local copies.

Synopsis

bricks merge [alias] [--all] [--with-dependent-libs] [--no-nx-add] [--ref <ref>] [--json] [--dry-run]

Flags

Flag	Behavior
--all	Merge every installed brick in dependency-first order.
--with-dependent-libs	With one alias, merge installed source dependencies first.
--no-nx-add	Do not initialize missing Nx tooling packages automatically.
--ref <ref>	Merge from a specific source ref instead of the recorded ref.

Behavior

1. Resolve one installed brick, or every installed brick when --all is set.
2. Pull the related source repo.
3. Determine the recorded base commit, local copy, and incoming source commit.
4. Perform a three-way merge for changed files.
5. Write clean merges into the consumer workspace.
6. Leave standard Git conflict markers in files that cannot merge cleanly.
7. Report divergent binary files as conflicts without rewriting local bytes.
8. Keep the install record at the old base commit while conflicts remain.
9. Initialize missing incoming Nx tooling packages after a clean merge.
10. Reconcile incoming local-manifest package requirements.
11. Advance the install record after the merge completes cleanly.

When merging one alias, Bricks detects installed source dependencies for that brick. In interactive human mode, it prompts to merge all dependencies or only the selected brick. In non-interactive mode, use --with-dependent-libs to merge the installed dependency bricks too. Partial dependency selection is not supported.

Package reconciliation is best effort during merge. Failed Nx initializers record nx-add-failed; package-manager failures record package-reconcile-failed. Both preserve the source merge and consumer dependencies.

Conflict Model

Bricks should not invent a separate conflict workflow. Consumers resolve conflicts the same way they resolve normal Git merge conflicts: edit files, run tests, and commit the result.

For divergent binary files, Bricks cannot place textual conflict markers. It reports the binary path as conflicted and leaves the local file untouched. The consumer replaces or keeps the file manually, then runs bricks merge continue.

bricks merge continue <alias>

Finish a merge after manual conflict resolution.

Synopsis

bricks merge continue <alias> [--all] [--no-nx-add] [--json] [--dry-run]

Flags

Flag	Behavior
--all	Continue every pending merge state in a batch.
--no-nx-add	Do not initialize missing Nx tooling packages automatically.

Behavior

1. Read .bricks/merge/<alias>.json.
2. Refuse to continue while copied text files still contain conflict markers.
3. Initialize missing incoming Nx tooling packages.
4. Reconcile incoming local-manifest package requirements.
5. Advance the install record to the incoming source commit.
6. Remove the merge-state file.

As with a clean merge, Nx initializer and package reconciliation failures record warnings without blocking merge completion.

bricks remove <alias>

Remove an installed-brick record without deleting copied source files.

Synopsis

bricks remove <alias> [--json] [--dry-run]

Behavior

1. Refuse to remove a record while it has unresolved merge state.
2. Remove the install record from .bricks/config.json.
3. Leave copied source files in the consumer workspace.

bricks status

Show sources and installed bricks.

Synopsis

bricks status [--json]

Output

The human output should show:

• configured sources,
• pulled source commits,
• installed aliases,
• target paths,
• recorded base commits,
• whether source updates are available,
• whether any installed brick has unresolved merge conflicts.

bricks diff <alias>

Show the difference between an installed local copy and a source commit.

Synopsis

bricks diff <alias> [--ref <ref>] [--json]

Behavior

1. Resolve the installed brick.
2. Resolve the source commit.
3. Compare local files against source files.
4. Print a human diff by default or structured file changes with --json.

Binary differences are returned as structured entries with binary: true instead of text patches.

bricks contribute plan <source>

Plan which local installed-brick edits could be contributed back to a source repo.

Synopsis

bricks contribute plan <source> \
  [--ref <ref>] \
  [--json] [--dry-run]

Flags

Flag	Behavior
--ref <ref>	Source ref to refresh and contribute against.

Behavior

1. Refresh the source repo and analysis for the selected ref.
2. Scan every installed brick from <source>.
3. Compare each installed file against that install record's source baseCommit.
4. Omit local files ignored by the consumer workspace's Git ignore rules.
5. Print candidate files with source path, target path, status, and whether the source also changed since install.

bricks contribute open <source>

Create a dedicated writable source worktree and apply every candidate local edit as uncommitted source changes.

Synopsis

bricks contribute open <source> \
  [--ref <ref>] \
  [--branch <name>] \
  [--editor <command>] \
  [--json] [--dry-run]

Flags

Flag	Behavior
--ref <ref>	Source ref to refresh and contribute against.
--branch <name>	Dedicated contribution branch name.
--editor <command>	Editor command used in interactive human mode.

Behavior

1. Recompute the contribution plan for <source>.
2. Require at least one candidate file.
3. Create .bricks/worktrees/<source>/<branch> from the refreshed source ref.
4. Apply all candidates with a reverse three-way merge: source base, current source, and local consumer edit.
5. Preserve conflict markers when text files conflict.
6. Persist a contribution session under .bricks/contributions/.
7. In interactive human mode, launch the configured editor when available.

Review the worktree with normal Git and IDE tools. Keep generic source changes, edit what needs cleanup, and drop consumer-only changes with commands such as git restore -- <path> for tracked files or git clean -f -- <path> for untracked files.

bricks contribute status <source>

Show the active contribution session for a source.

Synopsis

bricks contribute status <source> [--json]

bricks contribute commit <source>

Commit the reviewed source contribution worktree.

Synopsis

bricks contribute commit <source> [--message <message>] [--json]

Flags

Flag	Behavior
--message <message>	Commit message for source edits.

Behavior

1. Require an active opened contribution worktree.
2. Require conflict markers to be resolved.
3. Stage the current worktree state.
4. Create a commit on the dedicated contribution branch.

bricks contribute push <source>

Push the prepared source contribution branch.

Synopsis

bricks contribute push <source> \
  [--remote <name>] \
  [--branch <name>] \
  [--json]

Flags

Flag	Behavior
--remote <name>	Git remote to push to. Defaults to origin.
--branch <name>	Remote branch name to update.

Behavior

1. Require an active opened contribution worktree.
2. Require the source worktree to be clean.
3. Push HEAD to the selected remote branch.
4. Return a GitHub compare URL when the remote is a GitHub repository.

bricks doctor

Validate Bricks state in the consumer workspace.

Synopsis

bricks doctor [--json]

Checks

• .bricks/config.json exists and parses.
• Configured sources are reachable.
• Source caches exist under .bricks/sources/<name>.
• Install record paths are safe workspace-relative paths.
• Installed target paths exist.
• Copied projects are visible to Nx.
• Package dependencies, dev dependencies, and Nx tooling packages are present.
• Merge conflict state is reported clearly.
• Install warnings, such as failed Nx metadata normalization, are reported.