CLI 参考

Framedash CLI 提供从终端访问遥测数据、分析和项目管理的功能。支持在 CI/CD 流水线中自动上传地图和同步内容。

安装

npm install -g @framedash/cli

认证

通过环境变量设置 API 密钥：

export FRAMEDASH_API_KEY=fd_your_api_key_here

或使用 --api-key 显式传递：

framedash status --api-key fd_your_api_key_here

验证密钥是否有效：

framedash auth

通用选项

大多数命令接受以下选项：

选项	说明
--api-key <key>	API 密钥（或 FRAMEDASH_API_KEY 环境变量）
--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（api.framedash.dev/api）不同，后者用于直接调用 REST API。

命令

framedash auth

验证 API 密钥并显示关联的项目。

framedash auth

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

framedash status

显示项目健康状态。

framedash status

framedash dashboard

显示仪表盘 KPI（DAU、MAU、会话、事件数）。

framedash dashboard --days 30

选项	值	默认值
--days	7, 14, 30, 90	30

注意

CLI --help 显示 1, 7, 14, 30，但 API 实际接受 7, 14, 30, 90。使用 --days 1 会返回 400 错误。以上为 API 实际接受的值。

framedash retention

显示玩家留存率队列（D1、D7、D30）。

framedash retention --days 14

选项	值	默认值
--days	7, 14, 30, 90	30

注意

与 dashboard 相同的 CLI 帮助文本差异。API 实际接受的值为 7, 14, 30, 90。

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 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 alerts

管理性能告警规则。

# 告警规则列表
framedash alerts list

# 创建新告警规则
framedash alerts create --name "FPS Alert" --map-id <uuid> \
  --threshold-profile-id <uuid> --metric fps

# 更新告警规则
framedash alerts update <alert-id> --name "Updated Alert"

# 停用告警规则
framedash alerts delete <alert-id>

framedash maps

管理游戏地图。

# 地图列表
framedash maps list

# 通过地图标识符删除
framedash maps delete <map-id>

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	预览但不发送

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

在 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 集成指南。

下一步

• API 参考 — REST API 详细信息
• CI/CD 集成 — Jenkins 和 TeamCity 流水线示例
• CI 性能分析 — 自动性能分析设置