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

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 --help（または framedash <command> --help）で確認してください。

`framedash auth`

API キーの検証と紐付けプロジェクトの表示。

framedash auth

オプション: --api-key, --base-url, --format

--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 でも同じパス規約です）、サーバーオリジンごとにキー付けされて自動でリフレッシュされます。トークンの値が出力されることはありません。

framedash logout はトークンをサーバー側で失効させ（ベストエフォート）、解決されたベース URL のローカル認証情報を削除します。 --all を付けると全オリジンをクリアします。 API キーには影響しません。

framedash logout
framedash logout --all

明示的な --api-key、--api-key-file、FRAMEDASH_API_KEY は、保存済みのログインより常に優先されます。そのため CI では framedash login ではなく FRAMEDASH_API_KEY で認証してください。 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

`framedash perf-diff`

2 つのビルドの 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>`	1 つのメトリクスに限定: `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 ジョブは、ビルドを自分自身と比較する前に早期に失敗します。

`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>`	シェル経由で起動するゲーム/プロファイリングコマンド（必須）
`--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 プロファイリングを参照してください。

`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 --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 threshold-profiles`

アラートルールが参照するパフォーマンスしきい値プロファイル（メトリクスごとの warn/good の帯）を管理します。

新しく作成したプロジェクトには、Default という名前の自動作成プロファイルが 1 つ用意されています（デバイスフィルターはすべてワイルドカード、しきい値は組み込みの既定値）。そのためアラートルールはすぐにプロファイルを参照でき、後から編集や追加ができます。

# しきい値プロファイル一覧
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 キー、または --scopes に resources:write を含めて実行した framedash login の OAuth セッションが必要です（既定のログインは analytics:read のみを要求します）。名前の重複や、まったく同一のデバイスフィルターの組み合わせ（5 つのフィルターがすべて一致）はサーバーが 409 で拒否しますが、一部だけ重なる組み合わせは作成でき、コマンドは重なったプロファイル名を報告します。成功すると CLI は Threshold profile created と作成したプロファイルを出力します。

framedash threshold-profiles delete <profileId>（@framedash/cli 0.1.8 以降）はプロファイルを削除します。このコマンドには resources:write スコープを持つ API キー、または --scopes に resources:write を含めて実行した framedash login の OAuth セッションが必要です（既定のログインは analytics:read のみを要求します）。アラートルールから参照されているプロファイル（主となるしきい値プロファイル、またはバンドルの一員）はサーバーが 409 で拒否します。アラートルールを無効化しても削除できるようにはならないため、先に該当するアラートルールを framedash alerts update <alert-id> --threshold-profile-ids <...> で別のプロファイルに付け替えてください。

`framedash maps`

ゲームマップの管理。

# マップ一覧
framedash maps list

# マップ ID でマップを削除
framedash maps delete <map-id>

ここで指定する識別子は、マップのキャプチャ時に付けた mapId スラッグです。内部の 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 ファイルがキャプチャメタデータのサイドカーとして扱われます。無関係な JSON も同じディレクトリにある場合は --metadata-pattern '*.capture.json' を指定し、サイドカー名を合わせてください。--metadata-pattern は @framedash/cli 0.1.7 には含まれません。より新しいリリースをインストールし、framedash map-capture --help に表示されることを確認してから使用してください。コマンドは選択された各 JSON を読み込んで検証し、そこで参照している画像をアップロードします。サイドカーは 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 の日時

具体例を示します。画像 arena.png（1024x1024 の俯瞰キャプチャ）と、その隣にサイドカー arena.json を ./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

ドライランはファイルごとに 1 行（map_id=..., image=..., bounds=[minX,minY]→[maxX,maxY], size=WxH）を出力し、続けて Done: N succeeded, M failed の要約を表示します。検証に失敗したファイルが 1 つでもあれば終了コード 1 で終わります。失敗が 0 件と報告されたら、実際にアップロードします。アップロードは /api/v1/maps/upload へのマルチパート 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 始まりのエントリ番号が表示されます。

レート制限

1 時間あたりの API レート制限はアカウント（テナント）単位で適用され、そのアカウントが持つすべてのプロジェクトと API キーで共有されます。 Free プランは 1 時間あたり 100 リクエスト、上位プランはそれ以上です。枠が共有されるため、並列で走る CLI の呼び出しや別々のキーは、いずれも同じプールを消費します。

429 が返ったときは、X-RateLimit-Reset のタイムスタンプを基準にスケジュールするのではなく、毎回 Retry-After ヘッダーに従います。どちらの値もスライディングウィンドウから算出されるため、表示されたリセット直後の実際の待ち時間を短く見積もることがあり、リセット時刻ちょうどに再試行すると再び 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 プロファイリング: 自動パフォーマンスプロファイリング設定

AI エージェント向け: llms.txt

CLI リファレンス

インストール

認証

共通オプション

コマンド

framedash auth

framedash login / framedash logout

framedash projects list

framedash status

framedash dashboard

framedash retention

framedash funnel

framedash builds

framedash perf-diff

framedash run-profile-test

framedash query

framedash alerts

framedash threshold-profiles

framedash maps

framedash map-capture