Custom Code CLI

> Use the Brickr CLI to initialize a project, connect a workspace, test nodes locally, publish to dev, promote to prod, and keep the CLI and SDK updated.

The CLI package is published as brickr. The SDK package used inside your project is @brickr/sdk.

Install and run

You can run the CLI either with npx or as a global binary:

npx brickr
npm install -g brickr
brickr

Brickr CLI requires Node.js 18 or newer.

Startup version check

On normal runs, the CLI checks npm for a newer published brickr version. If one exists, the version banner shows an update hint:

brickr v1.2.1  --  custom node engine  (update available: vX.Y.Z  --  run brickr update)

Use:

brickr update

to update the global CLI and the local SDK together.

Linked workspace requirement

All operational commands run against a linked Brickr project. If the current directory is not linked, Brickr stops with:

No workspace connected. Run: brickr init

That applies to:

  • brickr update
  • brickr dev
  • brickr deploy
  • brickr status
  • brickr nodes list
  • brickr secret ...
  • brickr assets sync

brickr init, brickr link, brickr help, and version output are the exceptions.

Initialize a project

brickr init

Creates the local project scaffold and connects it to a workspace through the browser flow.

brickr init

The command:

1. Asks for the project name 2. Asks for TypeScript or JavaScript 3. Opens Brickr in the browser for workspace connection 4. Creates package.json, brickr.config.ts|js, src/nodes/hello-world.br.ts|js, and .brickr/project.json 5. Runs npm install 6. Saves the linked workspace locally

npx brickr without a command is equivalent to npx brickr init.

Reconnects the current project to a workspace without recreating the scaffold.

brickr link

Use this when you want to move an existing project to another workspace or refresh the local connection.

Update commands

brickr update

Updates both layers:

  • the global brickr CLI
  • the local @brickr/sdk dependency in the current project
brickr update

brickr update cli

Updates only the global CLI:

brickr update cli

After installing the latest global package, Brickr explicitly resets the global brickr path so the shell points at the freshly installed binary.

brickr update sdk

Updates only the project SDK:

brickr update sdk

This runs npm install @brickr/sdk@latest in the current project.

Run update commands from inside the Brickr project you actually want to keep current. The CLI update is global, but the SDK update is project-local.

Local development

brickr dev

Runs every discovered .br.ts / .br.js node locally and watches for changes.

brickr dev

What it does:

  • Finds src/**/*.br.ts and src/**/*.br.js
  • Bundles them locally
  • Executes each node's run(ctx)
  • Builds test inputs from pin defaults and pin types
  • Prints inputs, output, logs, and execution time
  • Re-runs when node files change

This is a local test loop, not a cloud deploy.

brickr dev [node]

Runs only one node and keeps watching that same selector:

brickr dev main.hello-world
brickr dev hello-world
brickr dev "Hello World"

Selector matching is flexible. Brickr tries:

  • nodeKey
  • display name
  • relative file path
  • base filename
  • unique partial matches

If the selector matches more than one node, Brickr errors with an ambiguity message.

Local test inputs

When brickr dev executes a node, it creates inputs using this order:

1. Explicit pin default from the SDK 2. Type-based fallback for required pins

Current fallbacks are:

| Pin type | Local test value | |----------|------------------| | string | "" | | number | 0 | | boolean | false | | *:array | [] | | object / object:Name | {} | | any | null | | sequence | omitted | | optional or port-only pin | omitted |

Local secrets

Inside local dev, ctx.secret("NAME") reads from an environment variable with the same name:

export STRIPE_API_KEY=sk_test_...
brickr dev

If the variable is missing, the run fails with an explicit error.

Deployment commands

brickr deploy

Starts an interactive deploy flow and asks whether you want dev or prod.

brickr deploy

brickr deploy dev

Builds the current node files and publishes them to the workspace dev channel.

brickr deploy dev

Use this when you want to validate the latest node version inside the Builder.

brickr deploy prod

Promotes the current workspace dev versions to production.

brickr deploy prod

Use this only after you have tested the dev versions in Brickr.

Opening and editing cloud nodes

brickr open <nodeId>

Downloads the source of any code node from your workspace and writes it to src/nodes/ as a .br.ts file.

brickr open cnode-1234567890-ab12cd34

This is useful when:

  • The Builder AI created a node and you want to refine it locally
  • You want to reuse an existing cloud node as a starting point for a new one
  • You are working across machines and want to pull a node you authored elsewhere

After editing, deploy the updated node with:

brickr deploy

The file is written using the SDK format so it works with brickr dev and brickr deploy without any modification.

Status and inspection

brickr status

Shows the current project metadata and deployed node status.

brickr status

The output includes:

  • project name
  • language
  • linked workspace
  • API URL
  • deployed node versions in dev and prod
  • asset drift warning when code-managed assets differ from the workspace state

brickr nodes list

Lists deployed code nodes and their current dev/prod versions.

brickr nodes list

Secrets and assets

brickr secret list

Lists workspace secrets:

brickr secret list

Secrets managed from code are tagged as code-managed.

brickr secret create

Creates a new workspace secret interactively:

brickr secret create

This is useful for values you want available in the runtime via ctx.secret("NAME").

brickr assets sync

Syncs brickr.config.ts or brickr.config.js into the linked workspace.

brickr assets sync

This publishes:

  • enums
  • structures
  • secrets

from your local config file.

The .brickr/project.json file

The CLI stores link metadata in .brickr/project.json. It includes the project name, language, API URL, workspace identity, auth token, and connection history for the current project.

Use cases:

  • the workspace guard checks this file before running commands
  • deploy commands use it to authenticate with the Brickr API
  • status reads it to print project info

Do not hand-edit it unless you are deliberately repairing a broken local setup.

Because this file contains an auth token, treat it as sensitive local project state.

Typical command flows

Local authoring:

npx brickr
brickr dev
brickr assets sync
brickr deploy dev
brickr status
brickr deploy prod

Editing an AI-generated node:

brickr open <nodeId>
# edit src/nodes/<name>.br.ts in your editor
brickr dev <nodeKey>
brickr deploy

What's next?

| Topic | Description | |-------|-------------| | Overview | Architecture and lifecycle overview | | SDK | Define nodes, pins, assets, and helpers | | Workflow | Recommended local testing and publish flow |