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.
大多數指令支援 -j 或 --json 以輸出機器可讀的 JSON 格式。
BRICKS Foundation 管理(bricks device)
bricks device list
列出工作區中的所有裝置。
| 選項 | 說明 |
|---|
-k, --keyword <text> | 依關鍵字篩選裝置 |
-j, --json | 輸出為 JSON |
bricks device get <id>
顯示裝置的詳細資訊,包含硬體規格。
bricks device bind <passcode>
使用通行碼將新裝置綁定至工作區。
| 選項 | 說明 |
|---|
-n, --name <name> | 設定裝置名稱 |
bricks device control <id> <type>
傳送控制事件至裝置。
| 選項 | 說明 |
|---|
-p, --payload <json> | 隨事件傳送的 JSON 內容 |
bricks device refresh <id>
重新載入裝置上的應用程式。
bricks device clear-cache <id>
清除裝置上的快取。
bricks device screenshot <id>
擷取螢幕截圖並儲存至本機。
| 選項 | 說明 |
|---|
-o, --output <path> | 螢幕截圖的儲存路徑 |
--no-take | 擷取現有的螢幕截圖,不重新拍攝 |
bricks device monitor
即時監控裝置狀態。需要互動式終端機。
| 選項 | 說明 |
|---|
-g, --group <id> | 僅監控特定群組中的裝置 |
-i, --interval <seconds> | 輪詢間隔(預設:60) |
BRICKS Foundation 群組(bricks group)
bricks group list
列出所有裝置群組。
bricks group get <id>
顯示群組詳細資訊。
bricks group devices <id>
列出群組中的裝置及其線上/離線狀態。
bricks group dispatch <id> <action>
傳送動作至群組中的所有裝置。
可用動作: 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>
重新整理群組中的所有裝置。
bricks group monitor <id>
即時監控群組中的所有裝置。
| 選項 | 說明 |
|---|
-i, --interval <seconds> | 輪詢間隔 |
應用程式
bricks app new
在工作區中建立新應用程式。
| 選項 | 說明 |
|---|
-n, --name <name> | 應用程式名稱(必填) |
-d, --description <text> | 應用程式說明 |
--layout-width <px> | 版面寬度(畫素) |
--layout-height <px> | 版面高度(畫素) |
--example <key> | 從範例範本建立 |
--init | 建立後初始化本機 bricks-ctor |
-o, --output <dir> | 專案初始化的輸出目錄 |
-y, --yes | 略過確認提示 |
-j, --json | 輸出為 JSON |
bricks app list
列出所有應用程式。
| 選項 | 說明 |
|---|
-k, --keyword <text> | 依關鍵字篩選 |
-j, --json | 輸出為 JSON |
bricks app get <id>
顯示應用程式詳細資訊。
| 選項 | 說明 |
|---|
-c, --composed | 包含組合後的設定 |
-j, --json | 輸出為 JSON |
bricks app update <id>
更新應用程式的中繼資料或設定。
| 選項 | 說明 |
|---|
-n, --name <name> | 更新名稱 |
-d, --description <text> | 更新說明 |
-c, --config <json> | 以內嵌 JSON 提供設定 |
-f, --file <path> | 從檔案提供設定 |
--validate | 套用前驗證設定 |
bricks app check-config <path>
依 BRICKS 結構描述驗證設定檔。
bricks app bind <id>
將裝置綁定或解除綁定至應用程式。
| 選項 | 說明 |
|---|
-b, --bind <ids> | 要綁定的裝置 ID |
-u, --unbind <ids> | 要解除綁定的裝置 ID |
bricks app short-edit <id>
不需完整發行即可套用快速屬性變更。
| 選項 | 說明 |
|---|
-l, --list <json> | 要套用的編輯清單(必填) |
bricks app short-refs <id>
列出可用於快速編輯的參考。
| 選項 | 說明 |
|---|
-k, --keyword <text> | 依關鍵字篩選 |
-t, --types <prefixes> | 依類型字首篩選 |
-j, --json | 輸出為 JSON |
bricks app trigger <id> <testId>
觸發應用程式上的自動化測試。
| 選項 | 說明 |
|---|
--play | 開始測試 |
--stop | 停止測試 |
--setup-at-launch | 在啟動時設定 |
-g, --match-group <group> | 指定特定裝置群組 |
bricks app release <id>
發行應用程式的新版本。
| 選項 | 說明 |
|---|
-c, --config <path|json> | 設定檔或 JSON(必填) |
--version <name> | 版本名稱 |
--changelogs <text> | 變更記錄文字 |
-j, --json | 輸出為 JSON |
bricks app project-pull <id>
從伺服器拉取應用程式原始程式碼檔案。
bricks app project-init <id>
從現有應用程式初始化 bricks-ctor。
| 選項 | 說明 |
|---|
-o, --output <dir> | 輸出目錄 |
-y, --yes | 略過提示,使用預設值 |
--no-git | 略過 Git 初始化 |
--no-install | 略過相依套件安裝 |
--no-github-actions | 略過 GitHub Actions 工作流程 |
--no-agents | 略過 AGENTS.md 產生 |
--no-claude | 略過 CLAUDE.md 產生 |
--gemini | 包含 GEMINI.md(預設關閉) |
-j, --json | 輸出為 JSON |
bricks module new
在工作區中建立新模組。
| 選項 | 說明 |
|---|
-n, --name <name> | 模組名稱(必填) |
-d, --description <text> | 模組說明 |
--layout-width <px> | 版面寬度(畫素) |
--layout-height <px> | 版面高度(畫素) |
--public | 使模組公開可用 |
--allow-modify | 允許其他人修改模組 |
--init | 建立後初始化本機 bricks-ctor |
-o, --output <dir> | 專案初始化的輸出目錄 |
-y, --yes | 略過確認提示 |
-j, --json | 輸出為 JSON |
bricks module list
列出所有模組。
| 選項 | 說明 |
|---|
-k, --keyword <text> | 依關鍵字篩選 |
-j, --json | 輸出為 JSON |
bricks module get <id>
顯示模組詳細資訊。
bricks module update <id>
更新模組的中繼資料或設定。
| 選項 | 說明 |
|---|
-n, --name <name> | 更新名稱 |
-d, --description <text> | 更新說明 |
-c, --config <json> | 以內嵌 JSON 提供設定 |
-f, --file <path> | 從檔案提供設定 |
--validate | 套用前驗證設定 |
bricks module short-edit <id>
不需完整發行即可套用快速屬性變更。
| 選項 | 說明 |
|---|
-l, --list <json> | 要套用的編輯清單(必填) |
bricks module short-refs <id>
列出可用於快速編輯的參考。
| 選項 | 說明 |
|---|
-k, --keyword <text> | 依關鍵字篩選 |
-t, --types <prefixes> | 依類型字首篩選 |
-j, --json | 輸出為 JSON |
bricks module release <id>
發行模組的新版本。
| 選項 | 說明 |
|---|
-c, --config <path|json> | 設定檔或 JSON(必填) |
--version <name> | 版本名稱 |
--changelogs <text> | 變更記錄文字 |
-j, --json | 輸出為 JSON |
bricks module project-pull <id>
從伺服器拉取模組原始程式碼檔案。
bricks module project-init <id>
從現有模組初始化 bricks-ctor。
| 選項 | 說明 |
|---|
-o, --output <dir> | 輸出目錄 |
-y, --yes | 略過提示,使用預設值 |
--no-git | 略過 Git 初始化 |
--no-install | 略過相依套件安裝 |
--no-github-actions | 略過 GitHub Actions 工作流程 |
--no-agents | 略過 AGENTS.md 產生 |
--no-claude | 略過 CLAUDE.md 產生 |
--gemini | 包含 GEMINI.md(預設關閉) |
-j, --json | 輸出為 JSON |
Media Flow 指令需要已啟用 Media Flow 的工作區。
列出所有 Media Flow 箱。
顯示 Media Flow 箱的詳細資訊。
列出 Media Flow 箱中的檔案。
| 選項 | 說明 |
|---|
-t, --types <types> | 依檔案類型篩選 |
-u, --user-tag <tag> | 依使用者標籤篩選(可重複) |
-l, --limit <n> | 限制結果數量 |
-o, --offset <n> | 分頁位移 |
-j, --json | 輸出為 JSON |
顯示檔案詳細資訊。
上傳一個或多個檔案至 Media Flow 箱。
| 選項 | 說明 |
|---|
-d, --description <text> | 檔案說明 |
-t, --user-tag <tag> | 新增標籤(可重複,最多 15 個) |
--image-version <spec> | 產生圖片版本(例如 800x600:FILL)(可重複) |
--image-version-type <format> | 圖片版本的輸出格式 |
--enable-ai-analysis | 對上傳的檔案執行 AI 分析 |
--ai-instruction <text> | AI 分析的自訂指示 |
--concurrency <n> | 平行上傳數量 |
-j, --json | 輸出為 JSON |
Activity Log
Activity Log 指令會查詢 Activity Log,僅限 Business 方案的工作區使用。單次查詢的時間範圍上限為 30 天。
本節的指令皆為唯讀查詢。可以使用 bricks al 作為 bricks activity-log 的簡短別名。
bricks activity-log events
查詢所有類型的 Activity Log 事件。
| 選項 | 說明 |
|---|
--start-time <datetime> | 起始時間,支援 ISO 8601 或相對時間(例如 1h、30m、2d)(必填) |
--end-time <datetime> | 結束時間(預設:目前時間) |
--device <id> | 依裝置 ID 篩選 |
--type <type> | 依事件類型篩選:general、data、local_sync |
--event-name <name> | 依事件名稱篩選 |
--subspace <id> | 依 Subspace ID 篩選 |
--sender <id> | 依 sender 篩選 |
--limit <n> | 顯示事件數量上限 |
-j, --json | 輸出為 JSON 陣列 |
--jsonl | 以 JSONL 串流輸出(每行一個 JSON 物件) |
若結果數量龐大,建議使用 --jsonl。事件會在接收時立即串流至 stdout,搭配 jq 等工具處理更為順暢。
bricks activity-log screenshots
列出裝置的截圖時間戳記。
| 選項 | 說明 |
|---|
--device <id> | 裝置 ID(必填) |
--start-time <datetime> | 起始時間,支援 ISO 8601 或相對時間(必填) |
--end-time <datetime> | 結束時間(預設:目前時間) |
-j, --json | 輸出為 JSON |
bricks activity-log screenshot
依指定時間戳記下載裝置的單張截圖。
| 選項 | 說明 |
|---|
--device <id> | 裝置 ID(必填) |
--ts <timestamp> | 截圖時間戳記,支援 ISO 8601 或 epoch 毫秒(必填) |
--space <id> | 工作區 ID(會自動從目前 profile 偵測) |
-o, --output <path> | 輸出檔案路徑(預設:screenshot-<device>-<ts>.jpg) |
--open | 下載後以系統預設檢視器開啟 |
BRICKS Buttress(bricks buttress)
將 BRICKS Buttress 伺服器與目前的工作區配對、檢視繫結狀態,並核發長期 access token。也可使用 bricks butr 作為簡寫。
bricks buttress bind
將本機的 Buttress 伺服器與目前 CLI profile 所屬的工作區配對,並寫入伺服器的 state.json。完成綁定後請重新啟動 Buttress 伺服器,變更才會生效。
| 選項 | 說明 |
|---|
-s, --server-id <id> | 覆寫自動偵測的 server id(預設為 buttress-<machineId>) |
-n, --name <name> | 儲存於工作區紀錄上的友善名稱 |
--state-dir <dir> | 覆寫 buttress state 目錄(預設為 ~/.bricks-cli/buttress) |
--print | 將 state.json 輸出至 stdout 而非寫入檔案(適合遠端設定) |
bricks buttress unbind
從工作區移除繫結並刪除本機 state.json。
| 選項 | 說明 |
|---|
-s, --server-id <id> | 要解除繫結的 server id(預設為本機機器 id) |
--state-dir <dir> | 覆寫 buttress state 目錄 |
--keep-local | 不要刪除本機 state.json 檔案 |
bricks buttress status
顯示本機 state.json 與工作區端的繫結伺服器清單。
| 選項 | 說明 |
|---|
--state-dir <dir> | 覆寫 buttress state 目錄 |
-j, --json | 以 { "local": …, "remote": [...] } 格式輸出 JSON |
bricks buttress issue-token
為非互動式呼叫端(CI 指令碼、CTOR 代理、ACP bridge)核發長期工作區 access token。
| 選項 | 說明 |
|---|
--ttl <seconds> | 存活時間(秒),預設為 30 天 |
-j, --json | 輸出為 JSON:{ token, expiresAt, workspaceId, jti } |
將 token 以 Authorization: Bearer <token> 標頭傳送,或附加於 WebSocket URL 的 ?access_token=<token> 查詢字串。
bricks buttress scan
透過 UDP 掃描區域網路上的 BRICKS Buttress 伺服器,並使用 HTTP /buttress/info 驗證每一台。會列出所有可達的伺服器(已繫結或未繫結),包含版本、認證狀態、所屬工作區,以及各 generator 的硬體能力。工作區與目前 CLI profile 相符的伺服器會被特別標示。
此指令不會核發 token。若需連線至已繫結伺服器,請於掃描後執行 bricks buttress issue-token。
| 選項 | 說明 |
|---|
-t, --timeout <ms> | 掃描逾時毫秒數(預設:3000) |
-p, --port <port> | UDP 探索連接埠(預設:8089) |
--udp-only | 略過 HTTP /buttress/info 驗證步驟 |
-j, --json | 輸出為 JSON:{ servers, workspaceId } |
自我更新
bricks update-cli
就地更新 CLI。藉由檢查 process.execPath 與 process.argv[1],自動偵測目前執行的 CLI 安裝方式(npm 全域、Bun 全域,或單一執行檔),然後執行對應的更新指令。當偵測不明確或主要方式失敗時,會改用 CDN 的二進位安裝程式(install.sh / install.ps1)。
| 選項 | 說明 |
|---|
-y, --yes | 略過確認提示(在非互動式 shell 中為必要) |
--channel <channel> | 覆寫通道:release 或 beta |
bricks update-cli # 更新前先詢問
bricks update-cli -y # 非互動式,適用於 CI 或指令碼
bricks update-cli --channel beta # 強制使用 beta 通道
當執行檔名為 bricks-beta 或目前版本帶有預先發行字尾時,通道預設為 beta;其餘情況則預設為 release。
bricks config show
顯示目前的 CLI 設定。
bricks config endpoint [environment]
顯示或變更 API 端點。
環境: prod(https://display.bricks.tools)、beta(https://display-beta.bricks.tools)、dev(http://localhost:3001)
工作區
bricks workspace
顯示目前工作區的詳細資訊。也可以使用 bricks ws。
互動模式
bricks interactive
啟動終端機 UI,用於瀏覽和控制裝置、應用程式、模組及媒體。也可以使用 bricks i。
操作鍵:
| 按鍵 | 動作 |
|---|
↑ / ↓ 或 j / k | 導覽 |
Enter | 選取 |
Esc | 返回 |
q | 離開 |
掃描本機網路上的 BRICKS DevTools 伺服器。
| 選項 | 說明 |
|---|
-t, --timeout <ms> | 掃描逾時(毫秒) |
-j, --json | 輸出為 JSON |
--verify | 透過 HTTP 驗證每台伺服器 |
--udp-only | 僅使用 UDP 廣播 |
-p, --port <port> | 自訂連接埠 |
裝置必須在進階設定中開啟 Enable LAN Discovery(預設已啟用)。
顯示 DevTools 伺服器的相關資訊(名稱、版本、裝置 ID、工作區、協定、驗證)。
| 選項 | 說明 |
|---|
-p, --port <port> | 自訂連接埠 |
--info | 顯示連線 URL(Web UI、CDP、MCP、MCP SSE、Info 端點)與授權資訊 |
CDP 指令需要 BRICKS Foundation 2.24 或更新版本。所有 CDP 指令共用下列選項:| 選項 | 說明 |
|---|
-a, --address <address> | DevTools 伺服器位址(必填) |
-p, --port <port> | 伺服器連接埠(預設:19851) |
--passcode <passcode> | 裝置通行碼 |
-j, --json | 以 JSON 格式輸出 |
透過 CDP 擷取裝置截圖並儲存至本機。
| 選項 | 說明 |
|---|
-o, --output <path> | 輸出檔案路徑(預設:screenshot-<timestamp>.png) |
列印 brick 元件樹。
| 選項 | 說明 |
|---|
-d, --depth <depth> | 最大深度,-1 代表完整樹狀結構(預設:3) |
以 CSS selector 查詢 brick 並顯示其屬性。
找出符合 CSS selector 的所有 brick。
以節點 ID 取得 brick 的全部屬性。
取得 brick 的尺寸與位置資訊(content、padding、border、margin)。
將 brick 解析為 JavaScript 物件並顯示其屬性。
聚焦某個 brick 元素。
在指定座標點選。
bricks devtools input type <text>
將文字輸入目前聚焦的元素。
派送按鍵事件(例如 Enter、Escape、Tab)。
擷取網路活動的快照。
| 選項 | 說明 |
|---|
--duration <ms> | 擷取時長(毫秒,預設:2000) |
取得已擷取網路請求的回應內容。
顯示持久化的系統儲存項目。
顯示記憶體中的系統儲存項目。
列出裝置上的所有 Data Bank。
從 Data Bank 的 store 查詢資料。
| 選項 | 說明 |
|---|
-l, --limit <count> | 最多擷取的項目數量(預設:25) |
-s, --skip <count> | 要略過的項目數量(預設:0) |
顯示 Generator 快取項目。
於裝置上執行 JavaScript 運算式。
以物件 ID 取得遠端 JavaScript 物件的屬性。
ACP 橋接
bricks desktop-acp-bridge
將 acpx 或其他 ACP 用戶端連線至正在執行的 CTOR 應用程式。橋接器在 ACP 用戶端與桌面應用程式的 Unix socket 之間傳遞 ACP JSON-RPC 訊息——預設使用 stdio,加上 --ws 則改為 WebSocket 伺服器。
# Stdio 模式(預設)——適用於 acpx 與其他 stdio ACP 用戶端
acpx --agent 'bricks desktop-acp-bridge' "summarize this project"
# WebSocket 模式——將 Unix socket 暴露為 WebSocket 伺服器
bricks desktop-acp-bridge --ws --auth-token <secret>
| 選項 | 說明 |
|---|
--ws | 啟動 WebSocket 伺服器以橋接 Unix socket,而非使用 stdio |
--host <host> | WebSocket 綁定主機(預設:0.0.0.0) |
--port <port> | WebSocket 連接埠(預設:8765) |
--auth-token <token> | 要求 WebSocket Authorization header 帶入此 Bearer token,亦可透過 BRICKS_DESKTOP_ACP_BRIDGE_TOKEN 環境變數設定 |
在 --ws 模式下,每個 WebSocket 用戶端都會獲得自己專屬的 ACP Unix socket 連線;一個 WebSocket 文字訊框對應一筆 JSON-RPC 訊息。預設綁定主機為 0.0.0.0,因為 WebSocket 模式設計用於 LAN 暴露(例如其他機器上的瀏覽器或行動用戶端)——請務必設定 --auth-token 並僅於受信任網路上執行。若要限制為本機,請使用 --host 127.0.0.1。
桌面應用程式必須正在執行,並已在 Settings > Agent 中啟用 ACP。詳細設定請參閱 ACP 參考。
MCP 伺服器
bricks mcp start
以 STDIO 模式啟動 BRICKS MCP 伺服器,供 AI 代理整合使用。
| 選項 | 說明 |
|---|
-t, --token <token> | 覆寫驗證 token |
將裝置 MCP 橋接至本機 CLI
使用 mcporter 將裝置的 MCP 端點橋接為本機 STDIO 伺服器:
npx mcporter --url http://<device-ip>:19851/mcp --header "Authorization: Bearer <passcode>"