Bricks CLI

BRICKS CLI

CLI for BRICKS Workspace API — manage devices, apps, modules, and media.

Installation (if not yet)

# Validate installed
which bricks

# npm
npm i -g @fugood/bricks-cli
# Bun
bun add -g @fugood/bricks-cli

Authentication

# Login with one-time passcode (get from https://control.bricks.tools)
bricks auth login <passcode>

# Check auth status
bricks auth status

# Switch profiles
bricks auth list
bricks auth use <profile>

Global --auth-profile Flag

Use -ap or --auth-profile to override the active profile for any command, without switching the stored profile:

# Run any command as a specific profile
bricks -ap staging device list
bricks --auth-profile production app list

# Also applies to login — saves token to the specified profile
bricks -ap staging auth login <passcode>

Priority: --auth-profile flag > BRICKS_PROFILE env > stored current profile.

Device Management

List & Info

# List all devices
bricks device list
bricks device list -j              # JSON output
bricks device list -k "lobby"      # Filter by keyword

# Get device details
bricks device get <device-id>
bricks device get <device-id> -j   # JSON output

Control

# Refresh device (reload app)
bricks device refresh <device-id>

# Clear device cache
bricks device clear-cache <device-id>

# Send control command
bricks device control <device-id> <type>
bricks device control <device-id> <type> -p '{"key":"value"}'

Screenshot

# Take and save screenshot
bricks device screenshot <device-id>
bricks device screenshot <device-id> -o /tmp/screen.png

# Fetch existing screenshot (no new capture)
bricks device screenshot <device-id> --no-take

Monitor (Interactive-tty needed)

# Monitor all devices (polls every 60s)
bricks device monitor

# Monitor specific group
bricks device monitor -g <group-id>

# Custom interval
bricks device monitor -i 30

Device Groups

# List groups
bricks group list

# Get group details
bricks group get <group-id>

# List devices in group with status
bricks group devices <group-id>

# Dispatch action to all devices in group
bricks group dispatch <group-id> <action>

# Refresh all devices in group
bricks group refresh <group-id>

# Monitor group
bricks group monitor <group-id>

Applications

# Create a new application
bricks app new -n "My App"
bricks app new -n "My App" -d "Description" --layout-width 192 --layout-height 108
bricks app new -n "My App" --example <key>     # Create from example template
bricks app new -n "My App" --init -y           # Create + initialize local project
bricks app new -n "My App" -j                  # JSON output

# List apps
bricks app list

# Get app details
bricks app get <app-id>

# Update app
bricks app update <app-id>

# Validate config against BRICKS schema
bricks app check-config ./config.json
bricks app check-config ./config.json -j       # JSON output

# Bind devices to app
bricks app bind <app-id>

# Quick property edit
bricks app short-edit <app-id>

# Pull source files
bricks app project-pull <app-id>

# Initialize local project from app
bricks app project-init <app-id>
bricks app project-init <app-id> -o ./my-app
bricks app project-init <app-id> -y          # Skip prompts, use defaults
bricks app project-init <app-id> --no-git    # Skip git init

Modules

# Create a new module
bricks module new -n "My Module"
bricks module new -n "My Module" --public --allow-modify
bricks module new -n "My Module" --init -y     # Create + initialize local project
bricks module new -n "My Module" -j            # JSON output

bricks module list
bricks module get <module-id>
bricks module update <module-id>
bricks module short-edit <module-id>
bricks module release <module-id>

# Initialize local project from module
bricks module project-init <module-id>
bricks module project-init <module-id> -o ./my-module -y

Project Init Options

Both app and module support these flags:

• -o, --output <dir> — output directory
• -y, --yes — skip prompts, use defaults
• --no-git — skip git initialization
• --no-install — skip bun install
• --no-github-actions — skip GitHub Actions workflow
• --no-agents — skip AGENTS.md
• --no-claude — skip CLAUDE.md
• --gemini — include GEMINI.md (off by default)

Media Flow

bricks media boxes              # List media boxes
bricks media box <box-id>       # Box details
bricks media files <box-id>     # Files in box (shows ready status)
bricks media file <file-id>     # File details (shows ready status)

# Upload files to a media box
bricks media upload <box-id> ./photo.jpg
bricks media upload <box-id> ./img1.jpg ./img2.png      # Multiple files
bricks media upload <box-id> ./photos/*.jpg -j           # JSON output

# Upload with tags and description
bricks media upload <box-id> ./file.pdf -t docs -t report -d "Monthly report"

# Upload with image processing options
bricks media upload <box-id> ./banner.jpg --image-version 250x250:FILL --image-version 800x600:BOUNDED
bricks media upload <box-id> ./logo.png --image-version-type png

# Upload with AI analysis
bricks media upload <box-id> ./photo.jpg --enable-ai-analysis
bricks media upload <box-id> ./photo.jpg --ai-instruction "Describe the scene"

# Control concurrency
bricks media upload <box-id> ./files/* --concurrency 5

Config

bricks config show              # Show current config
bricks config endpoint          # Show API endpoint
bricks config endpoint beta     # Switch to beta endpoint

Interactive Mode (Interactive-tty needed)

bricks interactive    # or: bricks i

DevTools (LAN Discovery)

# Scan LAN for DevTools servers via UDP broadcast
bricks devtools scan
bricks devtools scan -t 5000           # Custom timeout (ms)
bricks devtools scan -j                # JSON output
bricks devtools scan --verify          # Verify each server via HTTP

# Show connection URLs for a device
bricks devtools open <address>
bricks devtools open <address> -p 19853   # Custom port
bricks devtools open <address> --verify   # Verify reachable first

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

MCP Server

bricks mcp start      # Start MCP server (STDIO mode)

Bridging Device MCP to Local CLI

Use mcporter to bridge a device's MCP endpoint as a local MCP server (STDIO), so tools like Claude Code can connect to it:

# Bridge a device's MCP endpoint (requires passcode as Bearer token)
npx mcporter --url http://<device-ip>:19851/mcp --header "Authorization: Bearer <passcode>"

ACP Bridge (Desktop App)

Connect external ACP clients to the running BRICKS Project Desktop app (docs).

# Start the bridge (requires desktop app running with ACP enabled in Settings)
bricks desktop-acp-bridge

The bridge pipes ACP JSON-RPC over stdio ↔ the desktop app's Unix socket (~/.bricks-project-desktop/acp.sock). It shares the desktop app's settings, sessions, and MCP state.

See rule use-desktop-acp for full usage with acpx and OpenClaw.

Rules

• connect-local-device — Deploy the current app to a local LAN device, then monitor status, debug, and run automations via MCP
• use-desktop-acp — Connect to the BRICKS Project Desktop agent via ACP for headless prompting, session management, and multi-agent orchestration

Tips

• Use -j or --json on most commands for JSON output
• Device IDs are UUIDs — use device list to find them
• Get workspace token from: https://control.bricks.tools → Workspace Settings → API Token