CLI 參考

Framedash CLI 提供從終端機存取遙測資料、分析和專案管理的功能。支援在 CI/CD 管線中自動上傳地圖和同步內容。

安裝

需要 Node.js 與 npm。可以全域安裝，或用 npx 免安裝按需執行。

# 全域安裝
npm install -g @framedash/cli

# 或免安裝執行
npx @framedash/cli --help

驗證

透過環境變數提供 API 金鑰，或從檔案讀取：

# 環境變數
export FRAMEDASH_API_KEY=fd_your_api_key_here

# 或從檔案讀取（- 表示標準輸入）
framedash status --api-key-file ./read.key

驗證金鑰是否有效並查看關聯的專案：

framedash auth

警告

請優先使用 FRAMEDASH_API_KEY 或 --api-key-file，而非裸的 --api-key 旗標。命令列上傳入的金鑰會出現在行程清單和 shell 歷史中。CLI 本身在你使用 --api-key 時也會警告。

CLI 還可以用 framedash login 互動式登入，它會儲存 OAuth 工作階段，之後的讀取指令無需再傳金鑰。

共用選項

大多數指令接受以下選項：

選項	說明
--api-key <key>	API 金鑰（或 FRAMEDASH_API_KEY 環境變數）
--api-key-file <path>	從檔案讀取 API 金鑰（- 表示標準輸入）
--project-id <uuid>	專案 ID（或 FRAMEDASH_PROJECT_ID 環境變數）
--base-url <url>	API 主機 URL（預設：https://app.framedash.dev）
--format <fmt>	輸出格式：json、table、csv（預設：json）
-h, --help	顯示說明

注意

framedash auth 不需要 --project-id（僅驗證 API 金鑰）。 framedash map-capture 使用自己的選項解析器（詳見下方說明）。

注意

--base-url 是應用程式主機 URL。CLI 會在內部附加 API 路徑（例如 /api/v1/...）。這與 API 參考 中記載的 API 基礎 URL（app.framedash.dev/api）不同，後者用於直接呼叫 REST API。

尋找專案 ID

--project-id 所需的 UUID 可用 framedash projects list 查看。 framedash auth 也會印出你可存取的專案。

指令

本頁涵蓋最常用的指令。執行 framedash --help（或 framedash <command> --help）可取得隨版本變化的權威清單。

framedash auth

驗證 API 金鑰並顯示關聯的專案。

framedash auth

注意

framedash auth 透過一次需要 analytics:read 範圍的讀取呼叫來驗證金鑰。僅有 events:write 的 Ingest 金鑰無法以此方式驗證；要試用 Ingest 金鑰，只能透過 SDK 傳送事件。

使用 --format json 時，標準輸出只包含 JSON 文件，因此可以安全地傳給 jq 等工具。驗證結果與憑證來源狀態列仍會顯示在標準錯誤中。

framedash login / framedash logout

framedash login 使用 OAuth 2.1 授權碼流程與 PKCE（S256）互動式登入。它會在系統瀏覽器中開啟 {base-url}/oauth/authorize（使用回送重新導向），並最多等待 5 分鐘供你核准。

framedash login

選項	說明
--scopes <list>	要求的 scope（以空格分隔，預設 analytics:read）
--no-browser	印出授權 URL 而不開啟瀏覽器
--base-url <url>	授權伺服器（預設 https://app.framedash.dev）

權杖儲存在 ~/.config/framedash/credentials.json（遵循 XDG_CONFIG_HOME；Windows 上採用相同的路徑慣例），依伺服器 origin 建立索引鍵，並自動重新整理。權杖值絕不會被印出。

framedash logout 會在伺服器端撤銷權杖（盡力而為），並刪除已解析 base URL 的本機憑證。加上 --all 可清除所有 origin。API 金鑰不受影響。

framedash logout
framedash logout --all

明確指定的 --api-key、--api-key-file 或 FRAMEDASH_API_KEY 一律優先於已儲存的登入，因此 CI 應以 FRAMEDASH_API_KEY 而非 framedash login 進行驗證。透過 login 建立的授權可在儀表板的「設定」→「已連結應用程式」中查看與撤銷。

framedash projects list

列出你可存取的專案（id、name、createdAt）。具有 analytics:read 範圍的 API 金鑰或 OAuth 登入皆可使用，且無需 --project-id。僅有 events:write 的 Ingest 金鑰無法列出專案。自 @framedash/cli 0.1.4 起可用。

framedash projects list --format table

以 --format json|table|csv 設定輸出格式。

framedash status

顯示專案健康狀態。

framedash status

kpis.fetchedAt 是查詢 KPI 快照時的 Unix 毫秒時間戳。狀態通常使用伺服器快取；當 CI 或疑難排解需要新查詢的快照時，請使用 --fresh 略過快取。此選項未包含在 @framedash/cli 0.1.7 中；請安裝較新的版本，並在使用前確認 framedash status --help 中已列出此選項。

framedash dashboard

顯示儀表板 KPI（DAU、MAU、工作階段、事件數）。

framedash dashboard --days 30

選項	值	預設值
--days	7, 14, 30, 90	30

framedash retention

顯示玩家留存率世代（D1、D7、D30）。

framedash retention --days 14

選項	值	預設值
--days	7, 14, 30, 90	30

framedash funnel

分析事件漏斗，衡量各步驟之間的玩家轉換率。

framedash funnel --steps "player_spawn,player_death,player_respawn"

選項	說明	預設值
--steps	逗號分隔的事件名稱（必要，2-8 個步驟）	—
--window	時間窗口（秒）：3600、21600、86400、604800	86400
--days	時間範圍：7、14、30、90	30

framedash builds

依最新優先列出專案中出現過的建置 ID。用於為 framedash perf-diff 選擇比較對象。

framedash builds --days 30

選項	值	預設值
--days	7、14、30、90	30

分析用 --days 與熱力圖 days

分析指令（dashboard、retention、funnel、builds、perf-diff）的 --days 接受 7、14、30、90。這與熱力圖 API 的 days（1、7、14、30）是有意不同的集合。

framedash perf-diff

比較兩個建置的 P50/P95 效能（影格時間、記憶體、GPU 時間）。指定 --fail-on-regression 後，如果候選建置的退化超過閾值，指令會以退出碼 1 失敗。

framedash perf-diff --baseline "$BASE_SHA" --candidate "$GITHUB_SHA" \
  --threshold 5 --fail-on-regression

選項	說明
--baseline <id>	作為基準的 build_id（必要）
--candidate <id>	待測試的 build_id（必要）
--metric <name>	限定為單一指標：frame_time、memory、gpu_time、io.read_bytes、io.read_time_ms、io.read_ops、load_time_ms、mem.vram（預設為全部指標）。load_time_ms 需要 SDK 的地圖載入計時，mem.vram 需要 SDK 的 VRAM 取樣
--threshold <pct>	允許的退化百分比。預設值為 0
--fail-on-regression	偵測到效能退化時以非零退出
--days <n>	時間範圍：7、14、30、90（預設 30）
--map <id>	限定到一個地圖
--platform <name>	限定到一個平台

--baseline 與 --candidate 必須是不同的建置 ID。CLI 會拒絕相同的 ID，使設定錯誤的 CI 作業在把建置與自身比較之前盡早失敗。

isRegression 與 --threshold 的關係

輸出中每個指標的 isRegression 旗標僅表示方向：只要指標變差就為 true，不套用任何閾值。--threshold 的值只在你加上 --fail-on-regression 時影響結束碼。

framedash run-profile-test

在 CI 中端對端執行效能分析建置：匯出 FRAMEDASH_* 自動工作階段變數、啟動遊戲/分析指令、等待遙測資料寫入，再對基準執行 perf-diff 閘門。builds 和 perf-diff 的一鍵整合配套。

framedash run-profile-test \
  --command "./Build/Game.exe -nullrhi -ExecCmds='Automation RunTest Perf'" \
  --scenario nightly --api-key-file ci-read.key \
  --baseline "$BASE_SHA" --threshold 5 --fail-on-regression

選項	說明
--command <cmd>	透過 shell 啟動的遊戲/分析指令（必要）
--build-id <id>	候選建置的 build_id（預設：--commit，否則為 git HEAD）
--branch <name>	預設：git rev-parse --abbrev-ref HEAD
--commit <sha>	預設：git rev-parse HEAD
--scenario <name>	測試情境標籤
--ingest-timeout <s>	等待新遙測資料的最長秒數（預設 180）
--poll-interval <s>	輪詢寫入間隔秒數（預設 5）
--skip-wait	略過等待寫入
--baseline <id>	用來驗證候選建置的已知良好 build_id

--baseline、--metric、--threshold、--fail-on-regression、--days、--map 及 --platform 旗標的行為與 framedash perf-diff 完全相同。

已啟動的指令會繼承 FRAMEDASH_BUILD_ID / FRAMEDASH_GIT_BRANCH / FRAMEDASH_GIT_COMMIT / FRAMEDASH_TEST_SCENARIO。一旦 SDK 呼叫 BeginAutomatedSessionFromEnvironment()，每個事件就會自動加上標籤，無需為每個事件個別撰寫標籤程式碼。完整設定請參閱 CI 效能分析。

注意

閘門以 analytics:read 金鑰讀取遙測資料，已啟動的遊戲則以獨立的 events:write 寫入金鑰傳送遙測資料。為避免名稱衝突，請以 --api-key-file 傳遞閘門金鑰，而非 FRAMEDASH_API_KEY 環境變數，如此 FRAMEDASH_API_KEY 便能繼續作為遊戲的寫入金鑰使用。

framedash query

對遙測資料執行 SQL 查詢。

# 內嵌 SQL
framedash query "SELECT event_name, count() FROM events GROUP BY event_name"

# 從檔案讀取
framedash query --file ./queries/daily-active.sql

選項	說明
--file <path>	從檔案讀取 SQL 而非內嵌參數
--limit <n>	傳回的最大列數

注意

framedash query 需要具有 data:admin scope 的 API 金鑰（Full 金鑰）。framedash login 的 OAuth 登入絕不會攜帶 data:admin，因此僅靠登入無法執行此指令：請以 FRAMEDASH_API_KEY 或 --api-key / --api-key-file 傳入 Full 金鑰。

framedash alerts

管理效能警示規則。

# 警示規則清單
framedash alerts list

# 建立新警示規則
framedash alerts create --name "FPS Alert" --map-id <uuid> \
  --threshold-profile-id <uuid> --metric fps --threshold-level warn \
  --fail-percentage 20 --evaluation-days 7 --cell-size 25 \
  --cooldown-minutes 60

# 更新警示規則
framedash alerts update <alert-id> --name "Updated Alert"

# 停用警示規則
framedash alerts delete <alert-id>

注意

framedash alerts create 和 framedash alerts update 接受 --threshold-profile-ids <id1,id2,...>，可為單條規則附加至多 10 個閾值設定檔（@framedash/cli 0.1.6 及更新版本）。每個附加的閾值設定檔獨立觸發與恢復。單數形式的 --threshold-profile-id 仍保留用於單一設定檔的情況；alerts create 要求兩個參數中至少提供一個，且同時提供時以 --threshold-profile-ids 為準。

注意

alerts delete 不會銷毀規則，而是將其停用（isActive=false）。規則會被保留，可透過 framedash alerts update <alert-id> --is-active true 重新啟用。已停用的規則不計入方案的警示規則上限，因此重新啟用會受該上限約束。

framedash threshold-profiles

管理警示規則參照的效能閾值設定檔（每個指標的 warn/good 區間）。

新建立的專案會自帶一個自動建立、名為 Default 的設定檔（裝置篩選全部為萬用字元，閾值為內建預設值），因此警示規則可以立即參照設定檔，之後再自訂或新增。

# 閾值設定檔清單
framedash threshold-profiles list

# 建立閾值設定檔
framedash threshold-profiles create --name "Console 60fps" \
  --fps-good 60 --fps-warn 30 --platform windows

# 刪除閾值設定檔
framedash threshold-profiles delete <profileId>

framedash threshold-profiles create（@framedash/cli 0.1.7 及更新版本）用於建立設定檔。--name 為必填（最多 100 個字元）。閾值成對參數為選用，省略時回退到內建預設值：--fps-good / --fps-warn（FPS）、--frame-time-good / --frame-time-warn（毫秒）、--memory-good / --memory-warn（MB）、--gpu-time-good / --gpu-time-warn（毫秒）。FPS 越高越好（good 大於 warn），其餘越低越好（good 小於 warn）。裝置篩選（--platform、--resolution，如 1920x1080、--build-config、--gpu、--storage）為選用，省略的篩選按萬用字元處理。建立需要具備 resources:write 範圍的 API 金鑰，或在執行 framedash login 時透過 --scopes 包含 resources:write 而取得的 OAuth 工作階段（預設登入僅要求 analytics:read）；伺服器會以 409 拒絕重複的名稱或完全相同的裝置篩選組合（五個篩選全部相等），而部分重疊的組合可以建立成功，指令會報告重疊的設定檔名稱。成功時 CLI 印出 Threshold profile created 及建立的設定檔。

framedash threshold-profiles delete <profileId>（@framedash/cli 0.1.8 及更新版本）指令用於刪除設定檔。此指令需要具備 resources:write 範圍的 API 金鑰，或在執行 framedash login 時透過 --scopes 包含 resources:write 而取得的 OAuth 工作階段（預設登入僅要求 analytics:read）。仍被警示規則引用的設定檔（作為主閾值設定檔或組合成員）會被伺服器以 409 拒絕。停用警示規則並不會解除這項限制，因此請先用 framedash alerts update <alert-id> --threshold-profile-ids <...> 將這些警示規則指向另一個設定檔。

framedash maps

管理遊戲地圖。

# 地圖清單
framedash maps list

# 透過地圖識別碼刪除
framedash maps delete <map-id>

此處指定的識別碼是你在擷取地圖時賦予的 mapId slug，而非內部的 UUID 主鍵。

framedash map-capture

上傳擷取的地圖影像。此指令使用獨立的選項解析器，不使用共享的全域選項。

# 上傳預覽（模擬執行）
framedash map-capture --input-dir ./captures --upload --dry-run

# 上傳地圖擷取
framedash map-capture --input-dir ./captures --upload \
  --api-key fd_xxx --project-id <uuid>

選項	說明
--input-dir <path>	擷取影像目錄（必要）
--upload	實際執行上傳（必要）
--api-key <key>	上傳用 API 金鑰
--project-id <uuid>	目標專案
--base-url <url>	API 基礎 URL
--dry-run	預覽但不傳送
--metadata-pattern <glob>	僅讀取符合的 JSON 邊車（例如 *.capture.json）

輸入契約

--input-dir 以非遞迴方式掃描。預設每個 *.json 檔案都會被當作擷取中繼資料 sidecar。如果同一目錄還有無關 JSON，請使用 --metadata-pattern '*.capture.json' 並相應命名 sidecar。--metadata-pattern 未包含在 @framedash/cli 0.1.7 中；請安裝較新的版本，並在使用前確認 framedash map-capture --help 中已列出此選項。指令會讀取並驗證每個選取的 JSON，然後上傳其參照的影像。sidecar 透過 image_path 指向影像，該路徑相對於輸入目錄解析。絕對路徑以及逃逸出目錄的路徑會被拒絕，但輸入目錄內的子目錄是允許的。支援的影像格式為 .png、.jpg、.jpeg、.webp。

必要欄位：

欄位	型別	說明
version	字串	必須是字面值 "1.0"
map_id	字串	1~128 個字元
image_path	字串	相對於 --input-dir 的路徑
image_dimensions	物件	{ "width", "height" }，正整數
world_bounds	物件	{ "min": {x,y,z}, "max": {x,y,z} }，有限數值。max.x 必須大於 min.x，max.y 必須大於 min.y；z 無限制。取值為引擎世界單位（例如 Unreal Engine 中為公分）

選用欄位：

欄位	型別	說明
projection	字串	自由文字
capture_axis	字串	自由文字
coordinate_system	字串	自由文字
engine	字串	自由文字
build_id	字串	最多 255 個字元
captured_at	字串	ISO 8601 日期時間

完整範例。將 sidecar arena.json 與其影像 arena.png（1024x1024 的俯視擷取）一起放到 ./captures 中：

{
  "version": "1.0",
  "map_id": "arena_dust",
  "image_path": "arena.png",
  "image_dimensions": { "width": 1024, "height": 1024 },
  "world_bounds": {
    "min": { "x": -8192, "y": -8192, "z": 0 },
    "max": { "x": 8192, "y": 8192, "z": 2048 }
  },
  "engine": "UE5",
  "captured_at": "2026-07-16T09:30:00Z"
}

先用 --dry-run 驗證。它不需要憑證，也不會上傳任何內容：

framedash map-capture --input-dir ./captures --dry-run

模擬執行會為每個檔案印出一行（map_id=..., image=..., bounds=[minX,minY]→[maxX,maxY], size=WxH），隨後是 Done: N succeeded, M failed 摘要；只要有任何檔案驗證失敗，就以退出碼 1 結束。當它回報沒有失敗後，再實際上傳。上傳是向 /api/v1/maps/upload 發起的 multipart POST，需要具有 resources:write 範圍的 API 金鑰：

framedash map-capture --input-dir ./captures --upload \
  --api-key fd_xxx --project-id <uuid>

framedash content

管理內容註冊表（物品、武器、事件類型等）。

# 內容項目清單
framedash content list

# 從 JSON 檔案匯入內容
framedash content import ./game-content.json

# 透過 UUID 刪除
framedash content delete <uuid>

# 透過類型和內容 ID 刪除
framedash content delete --type weapon --content-id ak47

匯入 JSON 可以是陣列或 { "entries": [...] }。每個項目都需要非空字串欄位 contentType、contentId 與 displayName。選用的 description 和 category 必須是字串或 null；metadata 必須是物件或 null。傳送請求前的驗證錯誤會指出從 1 開始的項目編號。

速率限制

每小時的 API 速率限制以帳戶（租戶）為單位計算，由該帳戶擁有的所有專案與 API 金鑰共用。免費方案為每小時 100 次請求，更高方案則更多。由於額度共用，並行的 CLI 呼叫與不同的金鑰都會消耗同一個資源池。

遇到 429 時，請每次都遵循 Retry-After 回應標頭，而非圍繞 X-RateLimit-Reset 時間戳記安排重試。兩個值都由滑動視窗計算得出，因此在所公布的重設時刻剛過之後，它們可能低估實際等待時間，恰好在重設時刻重試可能再次觸發 429。

在 CI/CD 中使用

GitHub Actions 範例：

- name: Upload maps and import content
  env:
    FRAMEDASH_API_KEY: ${{ secrets.FRAMEDASH_API_KEY }}
    FRAMEDASH_PROJECT_ID: ${{ vars.PROJECT_ID }}
  run: |
    framedash map-capture --input-dir ./map-captures --upload
    framedash content import ./game-content.json

Jenkins 及 TeamCity 範例請參閱 CI/CD 整合指南。

下一步

• 事件表結構: framedash query 的欄位與規則
• 疑難排解: 確認事件已到達
• API 參考: REST API 的詳細說明
• CI/CD 整合: Jenkins 及 TeamCity 管線範例
• CI 效能分析: 自動效能分析設定