> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Full reference for all BRICKS CLI commands

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                     |

<Note>
  Deprecated — use `bricks ctor init <id>`. The old form still works and forwards to the new command.
</Note>

***

## 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                     |

<Note>
  Deprecated — use `bricks ctor init <id> --type module`. The old form still works and forwards to the new command.
</Note>

***

## BRICKS Projects (`bricks ctor`)

Scaffold, sync, compile, deploy, and simulate [bricks-ctor](/ctor-pkg) projects from the CLI.

<Tip>
  Generated bricks-ctor projects wrap these commands as package scripts — run `bun compile`, `bun deploy-app`, `bun update-app`, `bun pull-app`, and `bun invoke-simulator` from the project directory.
</Tip>

### `bricks ctor init <id>`

Initialize a BRICKS project from an application or module. Requires authentication. Replaces the deprecated `bricks app project-init` and `bricks module project-init`.

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

### `bricks ctor postinstall`

Regenerate the project's local `ctor/` library, MCP config, and skills. Migrates legacy bricks-ctor projects.

| Option             | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `--refresh-skills` | Overwrite the bundled skills                            |
| `--check`          | Report whether project files match the bundled snapshot |
| `-j, --json`       | Output as JSON (with `--check`)                         |

### `bricks ctor pull`

Pull the latest project files from BRICKS using a three-way Git merge.

| Option        | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `-f, --force` | Force the pull even when the working tree has uncommitted changes |

### `bricks ctor push`

Compile and push the configuration without creating a release.

| Option          | Description                                        |
| --------------- | -------------------------------------------------- |
| `--auto-commit` | Commit the compiled changes automatically          |
| `--no-check`    | Skip the server-side conflict check before pushing |
| `--no-validate` | Skip configuration validation                      |
| `-y, --yes`     | Skip confirmation prompts                          |

### `bricks ctor deploy`

Compile the project and release a new version.

| Option                     | Description                               |
| -------------------------- | ----------------------------------------- |
| `--changelogs <text>`      | Changelog text for the release            |
| `--changelogs-file <path>` | Read changelog text from a file           |
| `--auto-commit`            | Commit the compiled changes automatically |
| `--auto-version`           | Bump the version automatically            |
| `--version <version>`      | Version name for the release              |
| `-y, --yes`                | Skip confirmation prompts                 |

### `bricks ctor compile`

Typecheck and compile the project configuration, then validate it.

| Option       | Description                  |
| ------------ | ---------------------------- |
| `--no-check` | Skip the typecheck preflight |

### `bricks ctor simulator`

Run the project in the local Simulator window. Extra flags are passed through to the Simulator, for example `--skip-typecheck`, `--clear-cache`, `--screenshot`, `--screenshot-delay`, `--screenshot-width`, `--screenshot-height`, and `--screenshot-path`.

### `bricks ctor mcp`

Start the project's bricks-ctor MCP server over STDIO.

| Option            | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `--project <dir>` | Project directory (defaults to the current directory) |

***

## Media Flow

<Info>
  Media Flow commands require a workspace with Media Flow enabled.
</Info>

### `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

<Info>
  Activity Log commands query the [Activity Log](/foundation/activity-log), available on Business plan workspaces. The time range per query is capped at 30 days.
</Info>

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)                            |

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

### `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](/buttress) server with the current workspace, inspect bindings, mint long-lived access tokens, and wire an agent to a server's local functions. 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 }` |

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

### `bricks buttress scan`

Scan the LAN for [BRICKS Buttress](/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 }`       |

### `bricks buttress mcp-config`

Print — or write — the `.mcp.json` entry for a server's [local functions](/buttress/functions) MCP endpoint. Without `--url` it scans the LAN, prefers a server that advertises local functions, mints a workspace access token, and merges the entry into `.mcp.json` alongside your other MCP servers.

```bash theme={null}
bricks buttress mcp-config --write
bricks buttress mcp-config --url http://buttress.local:2080 --no-token
```

| Option               | Description                                                                     |
| -------------------- | ------------------------------------------------------------------------------- |
| `-u, --url <url>`    | Buttress server base URL; skips LAN discovery                                   |
| `--ttl <seconds>`    | Token time-to-live in seconds (defaults to 30 days)                             |
| `--no-token`         | Omit the access token, for a server running with `allow_unauthenticated = true` |
| `-n, --name <name>`  | Server key written in `.mcp.json` (default: `buttress-functions`)               |
| `-w, --write [file]` | Merge into `.mcp.json` instead of printing (defaults to `./.mcp.json`)          |
| `-t, --timeout <ms>` | Discovery timeout in milliseconds (default: `3000`)                             |
| `-j, --json`         | Print the entry as JSON                                                         |

<Warning>
  The entry embeds a long-lived workspace access token. Treat `.mcp.json` as a secret and keep it out of version control.
</Warning>

Discovery refuses to mint a token for a server that does not report your workspace — an unbound or foreign host is a mismatch, and any machine on the LAN can answer a discovery probe. Pass `--url` to target such a server deliberately, or `--no-token` for an unauthenticated one. A malformed existing `.mcp.json` is reported rather than overwritten.

***

## 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`                      |

```bash theme={null}
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
```

<Tip>
  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`.
</Tip>

***

## 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. Each device reports its auth state: `workspace-jwt` (workspace-token auth, shown when the device is bound to a workspace), `passcode`, `locked`, or `open` (older versions).

| 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                  |

<Tip>
  Devices must have **Enable LAN Discovery** turned on in Advanced Settings (enabled by default).
</Tip>

### `bricks devtools open <address>`

Show information about a DevTools server (name, version, device ID, workspace, protocols, auth). The reported auth state is one of `workspace-jwt` (workspace-token auth, shown when the device is bound to a workspace), `passcode`, `locked`, or `open` (older versions).

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

### `bricks devtools issue-token`

Issue or refresh a workspace-scoped DevTools access token for the current profile and save it to the CLI config (`~/.bricks-cli/config.json`). The token itself is never printed — the command prints the profile, workspace, expiry, and token id.

| Option            | Description                                      |
| ----------------- | ------------------------------------------------ |
| `--ttl <seconds>` | Token time-to-live in seconds (default: 30 days) |
| `-j, --json`      | Output as JSON                                   |

<Note>
  DevTools commands acquire and refresh this token automatically, so you rarely need to run `issue-token` manually.
</Note>

***

## DevTools CDP commands

<Info>
  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 (only needed for passcode-protected devices) |
  | `-j, --json`              | Output as JSON                                               |

  When a device supports workspace auth and you are signed into its workspace, commands authenticate automatically with a cached token, re-issued on a `403` response.
</Info>

### `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.

### Simulator (`bricks devtools simulator`)

Inspect and export simulated thermal-printer output from a running [CTOR](/ctor) or Config Editor Simulator. Print history is kept in memory — up to 10 prints per printer, cleared on reload.

#### `bricks devtools simulator thermal-printer list`

List the captured thermal-printer prints.

#### `bricks devtools simulator thermal-printer print-result -o <file>`

Export a captured thermal-printer print to a file.

| Option                | Description      |
| --------------------- | ---------------- |
| `-o, --output <file>` | Output file path |

***

## ACP bridge

### `bricks desktop-acp-bridge`

Connect [acpx](https://github.com/openclaw/acpx) or other ACP clients to the running [CTOR](/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`.

```bash theme={null}
# 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.

<Info>
  The desktop app must be running with ACP enabled in **Settings** > **Agent**. See [ACP reference](/ctor/reference/acp) for setup details.
</Info>

***

## 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 |