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

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

두 빌드의 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`	회귀가 감지되면 0이 아닌 종료 코드로 종료
`--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 프로파일이 하나 포함되어 있으므로(장치 필터는 모두 와일드카드, 임계값은 기본 내장값), 알림 규칙이 곧바로 프로파일을 참조할 수 있으며 이후에 편집하거나 추가할 수 있습니다.

# 임계값 프로파일 목록
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(ms), --memory-good / --memory-warn(MB), --gpu-time-good / --gpu-time-warn(ms). FPS는 높을수록 좋고(good이 warn보다 큼), 나머지는 낮을수록 좋습니다(good이 warn보다 작음). 장치 필터(--platform, --resolution(예: 1920x1080), --build-config, --gpu, --storage)는 선택 사항이며, 생략한 필터는 와일드카드로 처리됩니다. 생성에는 resources:write 스코프를 가진 API 키, 또는 --scopes에 resources:write를 포함해 실행한 framedash login의 OAuth 세션이 필요합니다(기본 로그인은 analytics:read만 요청합니다). 서버는 이름 중복이나 완전히 동일한 장치 필터 조합(다섯 개 필터가 모두 일치)을 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을 읽고 검증한 뒤, 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

드라이 런은 파일마다 한 줄(map_id=..., image=..., bounds=[minX,minY]→[maxX,maxY], size=WxH)을 출력한 뒤 Done: N succeeded, M failed 요약을 표시하며, 검증에 실패한 파일이 하나라도 있으면 종료 코드 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부터 시작하는 항목 번호가 표시됩니다.

요청 제한

시간당 API 요청 제한은 계정(테넌트) 단위로 적용되며, 그 계정이 소유한 모든 프로젝트와 API 키가 공유합니다. Free 플랜은 시간당 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