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 参考 中的基础 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

选项：--api-key、--base-url、--format

注意

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 性能分析: 自动性能分析设置