# Bricks CLI

> BRICKS CLI

- Skill: `javimosch/bricks-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javimosch/bricks-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javimosch/bricks-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: javimosch (https://skillmd.com/u/javimosch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javimosch/bricks-cli

---


# BRICKS CLI

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

## Installation (if not yet)

```bash
# Validate installed
which bricks

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

## Authentication

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

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

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

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

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

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

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

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

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

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

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

```bash
bricks interactive    # or: bricks i
```

## DevTools (LAN Discovery)

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

```bash
bricks mcp start      # Start MCP server (STDIO mode)
```

### Bridging Device MCP to Local CLI

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

```bash
# 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](https://docs.bricks.tools/project)).

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