Command reference

Most commands support -j or --json for machine-readable JSON output.

BRICKS Foundation management (`bricks device`)

`bricks device list`

List all devices in the workspace.

Option	Description
`-k, --keyword <text>`	Filter devices by keyword
`-j, --json`	Output as JSON

`bricks device get <id>`

Show detailed information about a device, including hardware specs.

Option	Description
`-j, --json`	Output as JSON

`bricks device bind <passcode>`

Bind a new device to the workspace using its passcode.

Option	Description
`-n, --name <name>`	Set a name for the device

`bricks device control <id> <type>`

Send a control event to a device.

Option	Description
`-p, --payload <json>`	JSON payload to send with the event

`bricks device refresh <id>`

Reload the application on a device.

`bricks device clear-cache <id>`

Clear the cache on a device.

`bricks device screenshot <id>`

Take a screenshot and save it locally.

Option	Description
`-o, --output <path>`	Save path for the screenshot
`--no-take`	Fetch the existing screenshot without capturing a new one

`bricks device monitor`

Monitor device status in real time. Requires an interactive terminal.

Option	Description
`-g, --group <id>`	Monitor only devices in a specific group
`-i, --interval <seconds>`	Polling interval (default: 60)

BRICKS Foundation groups (`bricks group`)

`bricks group list`

List all device groups.

Option	Description
`-j, --json`	Output as JSON

`bricks group get <id>`

Show group details.

Option	Description
`-j, --json`	Output as JSON

`bricks group devices <id>`

List devices in a group with their online/offline status.

Option	Description
`-j, --json`	Output as JSON

`bricks group dispatch <id> <action>`

Send an action to all devices in a group. Available actions: refresh, clear-cache, system-menu-open, system-menu-close, system-info-open, system-info-close, local-sync-panel-open, local-sync-panel-close, debug-panel-open, debug-panel-close, logging-on, logging-off, test-panel-open, test-panel-close

`bricks group refresh <id>`

Refresh all devices in a group.

`bricks group monitor <id>`

Monitor all devices in a group in real time.

Option	Description
`-i, --interval <seconds>`	Polling interval

Applications

`bricks app new`

Create a new application in the workspace.

Option	Description
`-n, --name <name>`	Application name (required)
`-d, --description <text>`	Application description
`--layout-width <px>`	Layout width in pixels
`--layout-height <px>`	Layout height in pixels
`--example <key>`	Create from an example template
`--init`	Initialize a local bricks-ctor project after creation
`-o, --output <dir>`	Output directory for project initialization
`-y, --yes`	Skip confirmation prompts
`-j, --json`	Output as JSON

`bricks app list`

List all applications.

Option	Description
`-k, --keyword <text>`	Filter by keyword
`-j, --json`	Output as JSON

`bricks app get <id>`

Show application details.

Option	Description
`-c, --composed`	Include composed configuration
`-j, --json`	Output as JSON

`bricks app update <id>`

Update application metadata or configuration.

Option	Description
`-n, --name <name>`	Update name
`-d, --description <text>`	Update description
`-c, --config <json>`	Configuration as inline JSON
`-f, --file <path>`	Configuration from a file
`--validate`	Validate configuration before applying

`bricks app check-config <path>`

Validate a configuration file against the BRICKS schema.

Option	Description
`-j, --json`	Output as JSON

`bricks app bind <id>`

Bind or unbind devices to an application.

Option	Description
`-b, --bind <ids>`	Device IDs to bind
`-u, --unbind <ids>`	Device IDs to unbind

`bricks app short-edit <id>`

Apply quick property changes without a full release.

Option	Description
`-l, --list <json>`	List of edits to apply (required)

`bricks app short-refs <id>`

List available references for short edits.

Option	Description
`-k, --keyword <text>`	Filter by keyword
`-t, --types <prefixes>`	Filter by type prefixes
`-j, --json`	Output as JSON

`bricks app trigger <id> <testId>`

Trigger an automation test on an application.

Option	Description
`--play`	Start the test
`--stop`	Stop the test
`--setup-at-launch`	Set up at launch
`-g, --match-group <group>`	Target a specific device group

`bricks app release <id>`

Release a new version of an application.

Option	Description
`-c, --config <path\|json>`	Configuration file or JSON (required)
`--version <name>`	Version name
`--changelogs <text>`	Changelog text
`-j, --json`	Output as JSON

`bricks app project-pull <id>`

Pull the application source files from the server.

Option	Description
`-j, --json`	Output as JSON

`bricks app project-init <id>`

Initialize a bricks-ctor project from an existing application.

Option	Description
`-o, --output <dir>`	Output directory
`-y, --yes`	Skip prompts, use defaults
`--no-git`	Skip Git initialization
`--no-install`	Skip dependency installation
`--no-github-actions`	Skip GitHub Actions workflow
`--no-agents`	Skip AGENTS.md generation
`--no-claude`	Skip CLAUDE.md generation
`--gemini`	Include GEMINI.md (off by default)
`-j, --json`	Output as JSON

Modules

`bricks module new`

Create a new module in the workspace.

Option	Description
`-n, --name <name>`	Module name (required)
`-d, --description <text>`	Module description
`--layout-width <px>`	Layout width in pixels
`--layout-height <px>`	Layout height in pixels
`--public`	Make the module publicly available
`--allow-modify`	Allow others to modify the module
`--init`	Initialize a local bricks-ctor project after creation
`-o, --output <dir>`	Output directory for project initialization
`-y, --yes`	Skip confirmation prompts
`-j, --json`	Output as JSON

`bricks module list`

List all modules.

Option	Description
`-k, --keyword <text>`	Filter by keyword
`-j, --json`	Output as JSON

`bricks module get <id>`

Show module details.

Option	Description
`-j, --json`	Output as JSON

`bricks module update <id>`

Update module metadata or configuration.

Option	Description
`-n, --name <name>`	Update name
`-d, --description <text>`	Update description
`-c, --config <json>`	Configuration as inline JSON
`-f, --file <path>`	Configuration from a file
`--validate`	Validate configuration before applying

`bricks module short-edit <id>`

Apply quick property changes without a full release.

Option	Description
`-l, --list <json>`	List of edits to apply (required)

`bricks module short-refs <id>`

List available references for short edits.

Option	Description
`-k, --keyword <text>`	Filter by keyword
`-t, --types <prefixes>`	Filter by type prefixes
`-j, --json`	Output as JSON

`bricks module release <id>`

Release a new version of a module.

Option	Description
`-c, --config <path\|json>`	Configuration file or JSON (required)
`--version <name>`	Version name
`--changelogs <text>`	Changelog text
`-j, --json`	Output as JSON

`bricks module project-pull <id>`

Pull the module source files from the server.

Option	Description
`-j, --json`	Output as JSON

`bricks module project-init <id>`

Initialize a bricks-ctor project from an existing module.

Option	Description
`-o, --output <dir>`	Output directory
`-y, --yes`	Skip prompts, use defaults
`--no-git`	Skip Git initialization
`--no-install`	Skip dependency installation
`--no-github-actions`	Skip GitHub Actions workflow
`--no-agents`	Skip AGENTS.md generation
`--no-claude`	Skip CLAUDE.md generation
`--gemini`	Include GEMINI.md (off by default)
`-j, --json`	Output as JSON

Media Flow

Media Flow commands require a workspace with Media Flow enabled.

`bricks media boxes`

List all Media Flow boxes.

Option	Description
`-j, --json`	Output as JSON

`bricks media box <id>`

Show Media Flow box details.

Option	Description
`-j, --json`	Output as JSON

`bricks media files <boxId>`

List files in a Media Flow box.

Option	Description
`-t, --types <types>`	Filter by file type
`-u, --user-tag <tag>`	Filter by user tag (repeatable)
`-l, --limit <n>`	Limit number of results
`-o, --offset <n>`	Offset for pagination
`-j, --json`	Output as JSON

`bricks media file <id>`

Show file details.

Option	Description
`-j, --json`	Output as JSON

`bricks media upload <boxId> <files...>`

Upload one or more files to a Media Flow box.

Option	Description
`-d, --description <text>`	File description
`-t, --user-tag <tag>`	Add a tag (repeatable, max 15)
`--image-version <spec>`	Generate an image version (e.g., `800x600:FILL`) (repeatable)
`--image-version-type <format>`	Output format for image versions
`--enable-ai-analysis`	Run AI analysis on the uploaded file
`--ai-instruction <text>`	Custom instruction for AI analysis
`--concurrency <n>`	Number of parallel uploads
`-j, --json`	Output as JSON

Activity Log

Activity Log commands query the Activity Log, available on Business plan workspaces. The time range per query is capped at 30 days.

Commands in this section are read-only queries. Use bricks al as a shorter alias for bricks activity-log.

`bricks activity-log events`

Query activity log events across all event types.

Option	Description
`--start-time <datetime>`	Start time, ISO 8601 or relative (e.g., `1h`, `30m`, `2d`) (required)
`--end-time <datetime>`	End time (default: now)
`--device <id>`	Filter by device ID
`--type <type>`	Filter by event type: `general`, `data`, `local_sync`
`--event-name <name>`	Filter by event name
`--subspace <id>`	Filter by subspace ID
`--sender <id>`	Filter by sender
`--limit <n>`	Maximum number of events to display
`-j, --json`	Output as a JSON array
`--jsonl`	Stream as JSONL (one JSON object per line)

Use --jsonl for large result sets — it streams events to stdout as they arrive, which is friendlier for piping into tools like jq.

`bricks activity-log screenshots`

List screenshot timestamps captured from a device.

Option	Description
`--device <id>`	Device ID (required)
`--start-time <datetime>`	Start time, ISO 8601 or relative (required)
`--end-time <datetime>`	End time (default: now)
`-j, --json`	Output as JSON

`bricks activity-log screenshot`

Download a single screenshot image for a device at a specific timestamp.

Option	Description
`--device <id>`	Device ID (required)
`--ts <timestamp>`	Screenshot timestamp, ISO 8601 or epoch milliseconds (required)
`--space <id>`	Workspace ID (auto-detected from the active profile)
`-o, --output <path>`	Output file path (default: `screenshot-<device>-<ts>.jpg`)
`--open`	Open the downloaded file with the OS default viewer

BRICKS Buttress (`bricks buttress`)

Pair a BRICKS Buttress server with the current workspace, inspect bindings, and mint long-lived access tokens. Also available as bricks butr.

`bricks buttress bind`

Pair the local Buttress server with the workspace of the active CLI profile and write the server’s state.json. Restart the Buttress server after binding for the change to take effect.

Option	Description
`-s, --server-id <id>`	Override the auto-detected server id (defaults to `buttress-<machineId>`)
`-n, --name <name>`	Friendly name stored on the workspace record
`--state-dir <dir>`	Override the buttress state directory (defaults to `~/.bricks-cli/buttress`)
`--print`	Print `state.json` to stdout instead of writing to disk (useful for remote setups)

`bricks buttress unbind`

Remove the binding from the workspace and delete the local state.json.

Option	Description
`-s, --server-id <id>`	Server id to unbind (defaults to the local machine’s id)
`--state-dir <dir>`	Override the buttress state directory
`--keep-local`	Do not remove the local `state.json` file

`bricks buttress status`

Show the local state.json and the workspace-side list of bound servers.

Option	Description
`--state-dir <dir>`	Override the buttress state directory
`-j, --json`	Output as `{ "local": …, "remote": [...] }` JSON

`bricks buttress issue-token`

Mint a long-lived workspace access token for headless callers (CI scripts, CTOR agents, ACP bridges).

Option	Description
`--ttl <seconds>`	Time-to-live in seconds (defaults to 30 days)
`-j, --json`	Output as JSON: `{ token, expiresAt, workspaceId, jti }`

Send the token as an Authorization: Bearer <token> header or as ?access_token=<token> on the WebSocket URL.

`bricks buttress scan`

Scan the LAN for BRICKS Buttress servers via UDP and verify each one over HTTP /buttress/info. Lists every reachable server (bound or unbound) with version, auth state, bound workspace, and per-generator hardware caps. Servers whose workspace matches the active CLI profile are highlighted. This command does not mint a token. Run bricks buttress issue-token afterwards if you need to connect to a bound server.

Option	Description
`-t, --timeout <ms>`	Scan timeout in milliseconds (default: `3000`)
`-p, --port <port>`	UDP discovery port (default: `8089`)
`--udp-only`	Skip the HTTP `/buttress/info` verification step
`-j, --json`	Output as JSON: `{ servers, workspaceId }`

Self-update

`bricks update-cli`

Update the CLI in-place. Auto-detects how the running CLI was installed (npm global, Bun global, or the standalone binary) by inspecting process.execPath and process.argv[1], then runs the matching update command. Falls back to the binary installer (install.sh / install.ps1 from the CDN) when detection is inconclusive or the primary method fails.

Option	Description
`-y, --yes`	Skip confirmation prompts (required in non-interactive shells)
`--channel <channel>`	Override the channel: `release` or `beta`

bricks update-cli                  # prompts before updating
bricks update-cli -y               # non-interactive, for CI or scripts
bricks update-cli --channel beta   # force the beta channel

The channel defaults to beta when the binary is named bricks-beta or the running version carries a pre-release suffix; otherwise it defaults to release.

Configuration

`bricks config show`

Display the current CLI configuration.

Option	Description
`-j, --json`	Output as JSON

`bricks config endpoint [environment]`

Show or change the API endpoint. Environments: prod (https://display.bricks.tools), beta (https://display-beta.bricks.tools), dev (http://localhost:3001)

Workspace

`bricks workspace`

Show details about the current workspace. Also available as bricks ws.

Option	Description
`-j, --json`	Output as JSON

Interactive mode

`bricks interactive`

Launch the terminal UI for browsing and controlling devices, applications, modules, and media. Also available as bricks i. Controls:

Key	Action
`↑` / `↓` or `j` / `k`	Navigate
`Enter`	Select
`Esc`	Go back
`q`	Quit

DevTools

`bricks devtools scan`

Scan the local network for BRICKS DevTools servers.

Option	Description
`-t, --timeout <ms>`	Scan timeout in milliseconds
`-j, --json`	Output as JSON
`--verify`	Verify each server via HTTP
`--udp-only`	Use UDP broadcast only
`-p, --port <port>`	Custom port

Devices must have Enable LAN Discovery turned on in Advanced Settings (enabled by default).

`bricks devtools open <address>`

Show information about a DevTools server (name, version, device ID, workspace, protocols, auth).

Option	Description
`-p, --port <port>`	Custom port
`--info`	Show connection URLs (Web UI, CDP, MCP, MCP SSE, Info endpoint) and authorization details

DevTools CDP commands

CDP commands require BRICKS Foundation version 2.24 or later. All CDP commands share the following options:

Option	Description
`-a, --address <address>`	DevTools server address (required)
`-p, --port <port>`	Server port (default: `19851`)
`--passcode <passcode>`	Device passcode
`-j, --json`	Output as JSON

`bricks devtools screenshot`

Capture a device screenshot via CDP and save it locally.

Option	Description
`-o, --output <path>`	Output file path (default: `screenshot-<timestamp>.png`)

Brick inspection (`bricks devtools brick`)

`bricks devtools brick tree`

Print the brick component tree.

Option	Description
`-d, --depth <depth>`	Max depth, `-1` for full tree (default: `3`)

`bricks devtools brick query <selector>`

Find a brick by CSS selector and show its attributes.

`bricks devtools brick query-all <selector>`

Find all bricks matching a CSS selector.

`bricks devtools brick attributes <nodeId>`

Get all attributes of a brick by node ID.

`bricks devtools brick box-model <nodeId>`

Get dimensions and position (content, padding, border, margin) of a brick.

`bricks devtools brick resolve <nodeId>`

Resolve a brick to a JavaScript object and show its properties.

`bricks devtools brick focus <nodeId>`

Focus a brick element.

Input emulation (`bricks devtools input`)

`bricks devtools input tap <x> <y>`

Tap/click at the given coordinates.

`bricks devtools input type <text>`

Insert text into the currently focused element.

`bricks devtools input key <key>`

Dispatch a key event (e.g., Enter, Escape, Tab).

Network inspection (`bricks devtools network`)

`bricks devtools network list`

Capture a snapshot of network activity.

Option	Description
`--duration <ms>`	Capture duration in milliseconds (default: `2000`)

`bricks devtools network get <requestId>`

Get the response body for a captured network request.

Storage inspection (`bricks devtools storage`)

`bricks devtools storage system persist`

Show persistent system storage entries.

`bricks devtools storage system memory`

Show in-memory system storage entries.

`bricks devtools storage data-bank list`

List all Data Banks on the device.

`bricks devtools storage data-bank get <name> <store>`

Query data from a Data Bank store.

Option	Description
`-l, --limit <count>`	Max items to fetch (default: `25`)
`-s, --skip <count>`	Items to skip (default: `0`)

`bricks devtools storage generator-cache`

Show generator cache entries.

Runtime (`bricks devtools runtime`)

`bricks devtools runtime eval <expression>`

Evaluate a JavaScript expression on the device.

Option	Description
`--await`	Await promise result

`bricks devtools runtime properties <objectId>`

Get properties of a remote JavaScript object by its object ID.

ACP bridge

`bricks desktop-acp-bridge`

Connect acpx or other ACP clients to the running CTOR app. The bridge pipes ACP JSON-RPC messages between an ACP client and the desktop app’s Unix socket — over stdio by default, or as a WebSocket server with --ws.

# Stdio mode (default) — for acpx and other stdio ACP clients
acpx --agent 'bricks desktop-acp-bridge' "summarize this project"

# WebSocket mode — exposes the Unix socket as a WebSocket server
bricks desktop-acp-bridge --ws --auth-token <secret>

Option	Description
`--ws`	Start a WebSocket server that bridges the Unix socket instead of using stdio
`--host <host>`	WebSocket bind host (default: `0.0.0.0`)
`--port <port>`	WebSocket port (default: `8765`)
`--auth-token <token>`	Require this Bearer token in the WebSocket `Authorization` header. Can also be set via `BRICKS_DESKTOP_ACP_BRIDGE_TOKEN`

In --ws mode each WebSocket client gets its own dedicated connection to the ACP Unix socket; one WebSocket text frame equals one JSON-RPC message. The default bind host is 0.0.0.0 because WebSocket mode is intended for LAN exposure (e.g. browser or mobile clients on other machines) — always set --auth-token and only run on trusted networks. Use --host 127.0.0.1 to restrict to localhost.

The desktop app must be running with ACP enabled in Settings > Agent. See ACP reference for setup details.

MCP server

`bricks mcp start`

Start a BRICKS MCP server in STDIO mode for AI agent integration.

Option	Description
`-t, --token <token>`	Override the authentication token

Authentication Changelog

Documentation Index

​BRICKS Foundation management (bricks device)

​bricks device list

​bricks device get <id>

​bricks device bind <passcode>

​bricks device control <id> <type>

​bricks device refresh <id>

​bricks device clear-cache <id>

​bricks device screenshot <id>

​bricks device monitor

​BRICKS Foundation groups (bricks group)

​bricks group list

​bricks group get <id>

​bricks group devices <id>

​bricks group dispatch <id> <action>

​bricks group refresh <id>

​bricks group monitor <id>

​Applications

​bricks app new

​bricks app list

​bricks app get <id>

​bricks app update <id>

​bricks app check-config <path>

​bricks app bind <id>

​bricks app short-edit <id>

​bricks app short-refs <id>

​bricks app trigger <id> <testId>

​bricks app release <id>

​bricks app project-pull <id>

​bricks app project-init <id>

​Modules

​bricks module new

​bricks module list

​bricks module get <id>

​bricks module update <id>

​bricks module short-edit <id>

​bricks module short-refs <id>

​bricks module release <id>

​bricks module project-pull <id>

​bricks module project-init <id>

​Media Flow

​bricks media boxes

​bricks media box <id>

​bricks media files <boxId>

​bricks media file <id>

​bricks media upload <boxId> <files...>

​Activity Log

​bricks activity-log events

​bricks activity-log screenshots

​bricks activity-log screenshot

​BRICKS Buttress (bricks buttress)

​bricks buttress bind

​bricks buttress unbind

​bricks buttress status

​bricks buttress issue-token

​bricks buttress scan

​Self-update

​bricks update-cli

​Configuration

​bricks config show

​bricks config endpoint [environment]

​Workspace

​bricks workspace

​Interactive mode

​bricks interactive

​DevTools

​bricks devtools scan

​bricks devtools open <address>

​DevTools CDP commands

​bricks devtools screenshot

​Brick inspection (bricks devtools brick)

​bricks devtools brick tree

​bricks devtools brick query <selector>

​bricks devtools brick query-all <selector>

​bricks devtools brick attributes <nodeId>

​bricks devtools brick box-model <nodeId>

​bricks devtools brick resolve <nodeId>

​bricks devtools brick focus <nodeId>

​Input emulation (bricks devtools input)

​bricks devtools input tap <x> <y>

BRICKS Foundation management (`bricks device`)

`bricks device list`

`bricks device get <id>`

`bricks device bind <passcode>`

`bricks device control <id> <type>`

`bricks device refresh <id>`

`bricks device clear-cache <id>`

`bricks device screenshot <id>`

`bricks device monitor`

BRICKS Foundation groups (`bricks group`)

`bricks group list`

`bricks group get <id>`

`bricks group devices <id>`

`bricks group dispatch <id> <action>`

`bricks group refresh <id>`

`bricks group monitor <id>`

Applications

`bricks app new`

`bricks app list`

`bricks app get <id>`

`bricks app update <id>`

`bricks app check-config <path>`

`bricks app bind <id>`

`bricks app short-edit <id>`

`bricks app short-refs <id>`

`bricks app trigger <id> <testId>`

`bricks app release <id>`

`bricks app project-pull <id>`

`bricks app project-init <id>`

Modules

`bricks module new`

`bricks module list`

`bricks module get <id>`

`bricks module update <id>`

`bricks module short-edit <id>`

`bricks module short-refs <id>`

`bricks module release <id>`

`bricks module project-pull <id>`

`bricks module project-init <id>`

Media Flow

`bricks media boxes`

`bricks media box <id>`

`bricks media files <boxId>`

`bricks media file <id>`

`bricks media upload <boxId> <files...>`

Activity Log

`bricks activity-log events`

`bricks activity-log screenshots`

`bricks activity-log screenshot`

BRICKS Buttress (`bricks buttress`)

`bricks buttress bind`

`bricks buttress unbind`

`bricks buttress status`

`bricks buttress issue-token`

`bricks buttress scan`

Self-update

`bricks update-cli`

Configuration

`bricks config show`

`bricks config endpoint [environment]`

Workspace

`bricks workspace`

Interactive mode

`bricks interactive`

DevTools

`bricks devtools scan`

`bricks devtools open <address>`

DevTools CDP commands

`bricks devtools screenshot`

Brick inspection (`bricks devtools brick`)

`bricks devtools brick tree`

`bricks devtools brick query <selector>`

`bricks devtools brick query-all <selector>`

`bricks devtools brick attributes <nodeId>`

`bricks devtools brick box-model <nodeId>`

`bricks devtools brick resolve <nodeId>`

`bricks devtools brick focus <nodeId>`

Input emulation (`bricks devtools input`)

`bricks devtools input tap <x> <y>`

`bricks devtools input type <text>`