跳轉到主要內容

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>

顯示裝置的詳細資訊,包含硬體規格。
選項說明
-j, --json輸出為 JSON

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

列出所有裝置群組。
選項說明
-j, --json輸出為 JSON

bricks group get <id>

顯示群組詳細資訊。
選項說明
-j, --json輸出為 JSON

bricks group devices <id>

列出群組中的裝置及其線上/離線狀態。
選項說明
-j, --json輸出為 JSON

bricks group dispatch <id> <action>

傳送動作至群組中的所有裝置。 可用動作: refreshclear-cachesystem-menu-opensystem-menu-closesystem-info-opensystem-info-closelocal-sync-panel-openlocal-sync-panel-closedebug-panel-opendebug-panel-closelogging-onlogging-offtest-panel-opentest-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 結構描述驗證設定檔。
選項說明
-j, --json輸出為 JSON

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>

從伺服器拉取應用程式原始程式碼檔案。
選項說明
-j, --json輸出為 JSON

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>

顯示模組詳細資訊。
選項說明
-j, --json輸出為 JSON

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>

從伺服器拉取模組原始程式碼檔案。
選項說明
-j, --json輸出為 JSON

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 的工作區。

bricks media boxes

列出所有 Media Flow 箱。
選項說明
-j, --json輸出為 JSON

bricks media box <id>

顯示 Media Flow 箱的詳細資訊。
選項說明
-j, --json輸出為 JSON

bricks media files <boxId>

列出 Media Flow 箱中的檔案。
選項說明
-t, --types <types>依檔案類型篩選
-u, --user-tag <tag>依使用者標籤篩選(可重複)
-l, --limit <n>限制結果數量
-o, --offset <n>分頁位移
-j, --json輸出為 JSON

bricks media file <id>

顯示檔案詳細資訊。
選項說明
-j, --json輸出為 JSON

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

上傳一個或多個檔案至 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 或相對時間(例如 1h30m2d)(必填)
--end-time <datetime>結束時間(預設:目前時間)
--device <id>依裝置 ID 篩選
--type <type>依事件類型篩選:generaldatalocal_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)
--printstate.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.execPathprocess.argv[1],自動偵測目前執行的 CLI 安裝方式(npm 全域、Bun 全域,或單一執行檔),然後執行對應的更新指令。當偵測不明確或主要方式失敗時,會改用 CDN 的二進位安裝程式(install.sh / install.ps1)。
選項說明
-y, --yes略過確認提示(在非互動式 shell 中為必要)
--channel <channel>覆寫通道:releasebeta
bricks update-cli                  # 更新前先詢問
bricks update-cli -y               # 非互動式,適用於 CI 或指令碼
bricks update-cli --channel beta   # 強制使用 beta 通道
當執行檔名為 bricks-beta 或目前版本帶有預先發行字尾時,通道預設為 beta;其餘情況則預設為 release

設定

bricks config show

顯示目前的 CLI 設定。
選項說明
-j, --json輸出為 JSON

bricks config endpoint [environment]

顯示或變更 API 端點。 環境: prodhttps://display.bricks.tools)、betahttps://display-beta.bricks.tools)、devhttp://localhost:3001

工作區

bricks workspace

顯示目前工作區的詳細資訊。也可以使用 bricks ws
選項說明
-j, --json輸出為 JSON

互動模式

bricks interactive

啟動終端機 UI,用於瀏覽和控制裝置、應用程式、模組及媒體。也可以使用 bricks i 操作鍵:
按鍵動作
/ j / k導覽
Enter選取
Esc返回
q離開

DevTools

bricks devtools scan

掃描本機網路上的 BRICKS DevTools 伺服器。
選項說明
-t, --timeout <ms>掃描逾時(毫秒)
-j, --json輸出為 JSON
--verify透過 HTTP 驗證每台伺服器
--udp-only僅使用 UDP 廣播
-p, --port <port>自訂連接埠
裝置必須在進階設定中開啟 Enable LAN Discovery(預設已啟用)。

bricks devtools open <address>

顯示 DevTools 伺服器的相關資訊(名稱、版本、裝置 ID、工作區、協定、驗證)。
選項說明
-p, --port <port>自訂連接埠
--info顯示連線 URL(Web UI、CDP、MCP、MCP SSE、Info 端點)與授權資訊

DevTools CDP 指令

CDP 指令需要 BRICKS Foundation 2.24 或更新版本。所有 CDP 指令共用下列選項:
選項說明
-a, --address <address>DevTools 伺服器位址(必填)
-p, --port <port>伺服器連接埠(預設:19851
--passcode <passcode>裝置通行碼
-j, --json以 JSON 格式輸出

bricks devtools screenshot

透過 CDP 擷取裝置截圖並儲存至本機。
選項說明
-o, --output <path>輸出檔案路徑(預設:screenshot-<timestamp>.png

Brick 檢視(bricks devtools brick

bricks devtools brick tree

列印 brick 元件樹。
選項說明
-d, --depth <depth>最大深度,-1 代表完整樹狀結構(預設:3

bricks devtools brick query <selector>

以 CSS selector 查詢 brick 並顯示其屬性。

bricks devtools brick query-all <selector>

找出符合 CSS selector 的所有 brick。

bricks devtools brick attributes <nodeId>

以節點 ID 取得 brick 的全部屬性。

bricks devtools brick box-model <nodeId>

取得 brick 的尺寸與位置資訊(content、padding、border、margin)。

bricks devtools brick resolve <nodeId>

將 brick 解析為 JavaScript 物件並顯示其屬性。

bricks devtools brick focus <nodeId>

聚焦某個 brick 元素。

輸入模擬(bricks devtools input

bricks devtools input tap <x> <y>

在指定座標點選。

bricks devtools input type <text>

將文字輸入目前聚焦的元素。

bricks devtools input key <key>

派送按鍵事件(例如 EnterEscapeTab)。

網路檢視(bricks devtools network

bricks devtools network list

擷取網路活動的快照。
選項說明
--duration <ms>擷取時長(毫秒,預設:2000

bricks devtools network get <requestId>

取得已擷取網路請求的回應內容。

儲存檢視(bricks devtools storage

bricks devtools storage system persist

顯示持久化的系統儲存項目。

bricks devtools storage system memory

顯示記憶體中的系統儲存項目。

bricks devtools storage data-bank list

列出裝置上的所有 Data Bank。

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

從 Data Bank 的 store 查詢資料。
選項說明
-l, --limit <count>最多擷取的項目數量(預設:25
-s, --skip <count>要略過的項目數量(預設:0

bricks devtools storage generator-cache

顯示 Generator 快取項目。

Runtime(bricks devtools runtime

bricks devtools runtime eval <expression>

於裝置上執行 JavaScript 運算式。
選項說明
--await等待 promise 結果

bricks devtools runtime properties <objectId>

以物件 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>"