CLI 명령

Trackio는 MCP 서버를 시작하지 않고도 프로젝트, 실행, 지표, Space 정보를 조회할 수 있는 포괄적인 CLI 명령어 세트를 제공합니다. 명령어는 기본적으로 로컬 데이터에 대해 작동하며, --space가 제공되면 원격 HF Space에 대해 작동합니다. 이는 LLM 에이전트 및 자동화 스크립트에 특히 유용합니다. 구조화된 JSON 출력과 모든 실험 데이터에 대한 프로그래매틱 접근을 통해, Trackio는 LLM이 실행하는 자율적 ML 실험을 지원하도록 설계되었습니다.

원격 Spaces 쿼리

대시보드 데이터를 읽는 모든 list, get, query 명령은 로컬 데이터 대신 원격 Hugging Face Space를 쿼리할 수 있습니다. Space ID 또는 전체 URL을 --space 플래그와 함께 전달하세요:

# Using a Space ID
trackio list projects --space username/my-space

# Using a Space URL
trackio list projects --space https://username-my-space.hf.space

# Works with any list/get/query command
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space

비공개 Spaces의 경우 --hf-token을 전달하거나 huggingface-cli login을 통해 로그인되어 있는지 확인하세요:

trackio list projects --space username/private-space --hf-token hf_xxxxx

참고: show, status, sync, freeze, skills, registry, list spaces 명령은 --space를 지원하지 않습니다. Hugging Face Hub의 Trackio 대시보드를 확인하려면 trackio list spaces를 사용하고, trackio list projects --space username/my-space와 같은 명령에 해당 Space ID 중 하나를 전달하세요.

Registry 명령

레지스트리를 생성하고, 유용한 경우 링크하기 전에 타입이 지정된 컬렉션을 정의합니다:

trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model --description "Churn predictor"

로컬 아티팩트 버전을 연결하거나, 별칭을 이동하여 컬렉션 버전을 승격하거나, 버전을 연결 해제합니다:

trackio registry link models/churn-model experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0
trackio registry unlink models/churn-model v0

컬렉션과 해당 감사 이력을 확인합니다:

trackio registry list models
trackio registry show models/churn-model
trackio registry events models

모든 registry 명령은 bucket 기반 registry의 경우 --bucket-id org/bucket를, 구조화된 출력을 위해 --json를 지원합니다. --alias는 반복적으로 사용할 수 있습니다. 대상은 models/churn-model 또는 registry-models/churn-model 형식으로 작성할 수 있습니다.

link 명령은 로컬 Trackio 데이터에서 project/artifact:version-or-alias를 해석합니다. 접미사를 생략하면 latest로 해석됩니다. 원격 Space에만 존재하는 아티팩트를 게시하는 경우에도 Trackio가 소스의 원격 저장소 좌표를 기록할 수 있도록 Python API를 사용합니다.

Sync 명령

로컬 프로젝트를 Hugging Face Space에 업로드합니다:

trackio sync --project "my-project" --space-id "username/space_id"

static Space로 배포( HF Bucket에서 읽기, 서버 불필요):

trackio sync --project "my-project" --space-id "username/space_id" --sdk static

Static Spaces는 브라우저에서 데이터를 직접 제공하므로 공개 스냅샷 데이터가 필요합니다. --sdk static --private는 지원되지 않으며, 비공개 대시보드의 경우 기본 Gradio SDK를 사용하세요.

동기화되지 않은 데이터가 있는 모든 프로젝트를 해당 프로젝트에 구성된 Spaces로 동기화합니다:

trackio sync --all

플래그	설명
`--project`	동기화할 프로젝트의 이름(`--all`을 사용하지 않는 경우 필수)
`--space-id`	동기화할 HF Space ID(예: `username/space_id`). 제공되지 않으면 이전에 구성된 Space를 사용합니다.
`--all`	동기화되지 않은 데이터가 있는 모든 프로젝트를 동기화합니다
`--sdk`	라이브 서버에는 `gradio` (기본값), 읽기 전용 버킷 기반 Space에는 `static`
`--private`	새로운 Gradio Space를 생성하는 경우 Space를 비공개로 설정하세요. `--sdk static`은 지원하지 않습니다.
`--force`	확인 없이 기존 데이터베이스를 덮어쓰기

Freeze 명령

라이브 Gradio Space에서 읽기 전용 정적 Space 스냅샷을 생성합니다:

trackio freeze --space-id "username/my-space" --project "my-project"

사용자 지정 대상 Space를 지정합니다:

trackio freeze --space-id "username/my-space" --project "my-project" --new-space-id "username/my-snapshot"

플래그	설명
`--space-id`	소스 Gradio Space ID (필수)
`--project`	동결할 프로젝트 (필수)
`--new-space-id`	대상 정적 Space ID입니다. 기본값은 `{space_id}_static`입니다.
`--private`	static frozen snapshots은 지원되지 않습니다

참고: 소스는 /data에 버킷이 마운트된 Gradio Space여야 합니다. 대상 Space가 이미 존재하고 Trackio static Space가 아닌 경우, freeze는 덮어쓰기를 거부합니다. 동결된 Space는 스냅샷입니다. 이후 원본 Gradio Space에 동기화되는 메트릭은 freeze를 다시 실행하지 않는 한 동결된 static Space에 표시되지 않습니다. static 동결 스냅샷은 공개 대상 데이터를 필요로 하므로 trackio freeze --private는 지원되지 않습니다.

버전 업데이트

로컬에 설치된 Trackio 버전으로 기존 Trackio Space를 업그레이드합니다:

trackio bump username/my-space

trackio bump --space username/my-space도 동일한 작업을 수행합니다.

Space는 업그레이드 중일 때 일시 중지되므로, 학습 작업은 계속 Space의 버킷 인박스(log)에 기록됩니다. 데이터베이스는 같은 버킷의 trackio-backups/에 백업되고, Trackio 핀이 업데이트되며, 새 버전이 데이터를 마이그레이션하도록 Space가 재시작됩니다. 업그레이드된 Space가 시작에 실패하거나 이전보다 적은 행 수를 보고하는 경우, 백업과 이전 Space 파일이 복원됩니다.

원본 Space를 그대로 유지하려면, 로컬 버전을 실행하는 새 Space로 Space와 해당 버킷을 복사하세요:

trackio bump username/my-space --new-space username/my-space-v2 --new-bucket username/my-space-v2-bucket

플래그	설명
`space_id`	업그레이드할 Trackio Space(필수, 또는 `--space`로 전달)
`--new-space`	`space_id`의 복사본을 기반으로 이 Space를 생성하고, 기존 위치에서 업그레이드하지 않습니다
`--new-bucket`	`--new-space`의 버킷입니다. 기본값은 `{new_space}-bucket`입니다.

참고: bump는 /data에 버킷이 마운트된 Trackio 0.21.0 이상을 실행하는 Gradio Spaces를 지원하며, Space를 절대 다운그레이드하지 않습니다. 이전 Spaces는 버킷 대신 Hugging Face Dataset에 데이터를 저장했습니다.

명령어 목록

모든 프로젝트 나열

사용 가능한 모든 프로젝트를 나열합니다:

trackio list projects

JSON 형식으로 출력:

trackio list projects --json

Trackio Spaces 목록

Trackio 대시보드에 Hugging Face 계정과 조직이 소유한 Spaces를 나열합니다:

trackio list spaces

JSON 형식으로 출력:

trackio list spaces --json

특정 사용자 또는 조직 네임스페이스 아래에 있는 Trackio Spaces를 나열합니다:

trackio list spaces --author "username-or-org"

반환되는 Spaces의 수를 제한합니다:

trackio list spaces --limit 10

비공개 Spaces의 경우 --hf-token을 전달하거나 huggingface-cli login을 통해 로그인되어 있는지 확인하세요.

프로젝트의 실행 목록

특정 프로젝트의 모든 실행을 나열합니다:

trackio list runs --project "my-project"

JSON 형식으로 출력:

trackio list runs --project "my-project" --json

Run의 메트릭 목록

특정 run에서 추적되는 모든 metrics를 나열합니다:

trackio list metrics --project "my-project" --run "my-run"

JSON 형식으로 출력:

trackio list metrics --project "my-project" --run "my-run" --json

Run의 시스템 메트릭 나열

특정 run의 모든 시스템 메트릭(예: GPU 메트릭)을 나열합니다:

trackio list system-metrics --project "my-project" --run "my-run"

JSON 형식으로 출력:

trackio list system-metrics --project "my-project" --run "my-run" --json

리포트 목록

프로젝트에서 마크다운 리포트를 나열합니다(모든 런에 걸쳐):

trackio list reports --project "my-project"

특정 run에 대한 markdown 리포트를 나열합니다:

trackio list reports --project "my-project" --run "my-run"

JSON 형식으로 출력:

trackio list reports --project "my-project" --run "my-run" --json

트레이스 목록

프로젝트의 모든 run에 걸쳐 traces(에이전트 또는 대화 세션)를 나열합니다:

trackio list traces --project "my-project"

각 행은 트레이스의 상태, 실제 지연 시간, 비용, 연산 수, 그리고 해당 트레이스를 시작한 사용자 요청을 표시합니다. 실행, 단계 또는 텍스트로 필터링할 수 있습니다:

trackio list traces --project "my-project" --run "production"
trackio list traces --project "my-project" --step 12
trackio list traces --project "my-project" --search "rate limit"

검색은 메시지 내용, 트레이스 메타데이터, 각 스팬의 이름, 종류, 모델, 상태, 오류를 일치시킵니다. 정렬 및 페이지네이션을 제어합니다:

trackio list traces --project "my-project" --sort step_desc --limit 100 --offset 50

--sort는 request_time_desc(기본값), request_time_asc, step_asc, step_desc를 지원합니다. --json을 추가하면 각 trace에 대한 summary 집계 값이 포함됩니다.

명령 가져오기

Trace 가져오기

…

trackio get trace --project "my-project" --trace-id "fe04ed264a8a4bd6afcf266b56d9297e"

Trace fe04ed264a8a4bd6afcf266b56d9297e
  Run:      production
  Totals:   error | 25.0s | $0.33 | 101338 in / 1804 out tokens | 21 operation(s)

Execution:
  answer-research-question [span]  25.0s
    generate-research-response [span]  23.7s
      acquire-sandbox [span]  914ms
      dispatch-model-request [span]  2.18s
        provider-request [generation]  2.18s  my-model  8347->239 tok  $0.03
      ERROR run-bash-command [tool]  168ms
        -> {"exit_code": 2, "stderr": "hf datasets list: error: unrecognized arguments: --full"}

--trace-id는 trackio list traces가 출력하는 짧은 id 또는 전체 저장된 id를 받습니다. 스팬 입력 및 출력을 포함한 전체 trace를 보려면 --json을 추가하세요.

Trace 요약 가져오기

연산 이름별로 모든 스팬을 집계하여 지연 시간, 토큰, 비용이 어디에 쓰이는지, 그리고 어떤 연산이 실패하는지 확인합니다:

trackio get trace-summary --project "my-project"

operation                  | kind       | calls | errors | avg_ms  | max_ms  | input_tokens | output_tokens | cost_usd
provider-request           | generation | 205   | 0      | 3380.8  | 5535.0  | 2915829      | 63020         | 9.6928
run-bash-command           | tool       | 157   | 25     | 818.4   | 1548.0  | 0            | 0             | 0.0
acquire-sandbox            | span       | 48    | 0      | 2438.6  | 10615.0 | 0            | 0             | 0.0

--run으로 실행을 한 번으로 제한하거나, --json으로 기계가 읽을 수 있는 행을 출력합니다. 롤업이 다루지 않는 항목에 대해서는 trackio query project를 사용하여 traces 테이블을 직접 쿼리합니다. spans는 JSON 컬럼이므로 json_each를 사용할 수 있습니다.

프로젝트 요약 가져오기

실행 횟수와 최근 활동이 포함된 프로젝트의 상세한 요약을 가져옵니다:

trackio get project --project "my-project"

JSON 형식으로 출력:

trackio get project --project "my-project" --json

요약에는 다음이 포함됩니다:

프로젝트 이름
실행 횟수
모든 실행 목록
마지막 활동(모든 실행에 걸친 최대 스텝)

Run Summary 가져오기

메트릭과 구성을 포함한 특정 실행에 대한 상세한 요약을 가져옵니다:

trackio get run --project "my-project" --run "my-run"

JSON 형식으로 출력:

trackio get run --project "my-project" --run "my-run" --json

요약에는 다음이 포함됩니다:

프로젝트 및 실행 이름
로그 항목 수
마지막 단계
모든 지표 목록
실행 구성(내부 필드 제외)

메트릭 값 가져오기

실행(run)에서 특정 메트릭의 모든 값을 가져오기:

trackio get metric --project "my-project" --run "my-run" --metric "loss"

JSON 형식으로 출력:

trackio get metric --project "my-project" --run "my-run" --metric "loss" --json

출력에는 다음이 포함됩니다:

단계 번호
타임스탬프
메트릭 값

Step 또는 Time으로 필터링

특정 단계 또는 단계/타임스탬프 주변의 윈도우로 지표 값을 필터링할 수 있습니다. 이는 알림이 발동된 시점 주변의 지표를 검사하는 데 유용합니다.

# Get metric at exactly step 200
trackio get metric --project "my-project" --run "my-run" --metric "loss" --step 200

# Get metrics in a window around step 200 (±10 steps, the default)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200

# Get metrics in a window around step 200 (±50 steps)
trackio get metric --project "my-project" --run "my-run" --metric "loss" --around 200 --window 50

# Get metrics within ±60 seconds of a timestamp
trackio get metric --project "my-project" --run "my-run" --metric "loss" --at-time "2025-06-01T12:05:30" --window 60

플래그	설명
`--step N`	step N에서 정확히 메트릭을 반환합니다
`--around N`	step N 주변의 윈도우에서 메트릭을 반환합니다
`--at-time T`	ISO 8601 타임스탬프 T를 중심으로 한 윈도우에서 메트릭을 반환합니다
`--window W`	Window size: `--around`의 경우 ±steps, `--at-time`의 경우 ±seconds (기본값: 10)

Metrics 스냅샷 가져오기

Get all metrics at/around a step or timestamp in a single call. This is the fastest way for an agent to understand the state of a run at a specific point — for example, right when an alert fired.

# All metrics at step 200
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# All metrics in a window around step 200 (±5 steps)
trackio get snapshot --project "my-project" --run "my-run" --around 200 --window 5 --json

# All metrics within ±60 seconds of a timestamp
trackio get snapshot --project "my-project" --run "my-run" --at-time "2025-06-01T12:05:30" --window 60 --json

JSON 출력 예시:

{
  "project": "my-project",
  "run": "my-run",
  "around": 200,
  "window": 5,
  "metrics": {
    "loss": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.42},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.45}
    ],
    "accuracy": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.88},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.87}
    ],
    "lr": [
      {"step": 196, "timestamp": "2025-06-01T12:04:50", "value": 0.0001},
      {"step": 200, "timestamp": "2025-06-01T12:05:30", "value": 0.0001}
    ]
  }
}

시스템 메트릭 값 가져오기

런에 대한 시스템 메트릭 값을 가져옵니다. 메트릭 이름이 제공되지 않으면 모든 시스템 메트릭이 반환됩니다:

# Get all system metrics
trackio get system-metric --project "my-project" --run "my-run"

# Get a specific system metric
trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization"

JSON 형식으로 출력:

trackio get system-metric --project "my-project" --run "my-run" --metric "gpu_utilization" --json

리포트 내용 가져오기

Print markdown report entries for a specific report name in a run:

trackio get report --project "my-project" --run "my-run" --report "training_report"

JSON 형식으로 출력:

trackio get report --project "my-project" --run "my-run" --report "training_report" --json

쿼리 명령

trackio list 또는 trackio get로 이미 처리되지 않는 포괄적인 읽기 전용 SQL 쿼리가 필요할 때 trackio query를 사용하세요.

프로젝트 데이터베이스에 쿼리 실행

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

JSON 형식으로 출력:

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json

원격 Space 쿼리:

trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json

trackio query는 읽기 전용 SELECT, WITH 및 안전한 스키마 PRAGMA 쿼리만 지원합니다.

일반적인 스키마 검사 예시:

# Inspect table columns
trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

# Inspect indexes
trackio query project --project "my-project" --sql "PRAGMA index_list(alerts)"

# List tables
trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"

응답에는 다음이 포함됩니다:

project
query
columns
rows
row_count

SQLite와 parquet 레이아웃의 전체 내용은 Storage Schema and Direct Queries를 참조하세요.

출력 형식

모든 list, get, query 명령은 두 가지 출력 형식을 지원합니다:

Human-readable (기본값): 터미널에서 보기 적합한 포맷된 텍스트 출력
JSON (--json 플래그 사용): 프로그래밍 방식으로 소비하기에 적합한 구조화된 JSON 출력

오류 처리

CLI 명령어에는 포괄적인 검증 및 오류 처리가 포함되어 있습니다:

프로젝트가 존재하지 않으면 오류 메시지가 표시됩니다
프로젝트에 실행이 없으면 오류 메시지가 표시됩니다
런에 해당 메트릭이 없으면 오류 메시지가 표시됩니다
런에 리포트가 없으면 오류 메시지가 표시됩니다
쿼리가 읽기 전용이 아닌 경우, CLI는 오류와 함께 종료됩니다

모든 오류는 stderr에 기록되며, 명령은 0이 아닌 종료 코드로 종료됩니다.

예시 워크플로

Trackio 데이터를 탐색하는 일반적인 워크플로우는 다음과 같습니다:

# 1. List all projects
trackio list projects

# 2. List runs in a project
trackio list runs --project "my-project"

# 3. Get project summary
trackio get project --project "my-project"

# 4. Get run summary
trackio get run --project "my-project" --run "my-run"

# 5. List metrics in the run
trackio list metrics --project "my-project" --run "my-run"

# 6. Get specific metric values
trackio get metric --project "my-project" --run "my-run" --metric "loss"

# 7. Get all metrics at a specific step (e.g. where an alert fired)
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json

# 8. Get system metrics (if available)
trackio list system-metrics --project "my-project" --run "my-run"

# 9. List reports in a run
trackio list reports --project "my-project" --run "my-run"

# 10. Print report markdown in terminal
trackio get report --project "my-project" --run "my-run" --report "training_report"

# 11. Run a direct SQL query
trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name"

원격 Space 쿼리

동일한 워크플로우는 원격 Space에도 적용됩니다. --space를 추가하면 됩니다:

# List projects on a remote Space
trackio list projects --space username/my-space

# Get metric values from a remote Space
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space --json

사용 사례

LLM 에이전트

이 CLI 명령어는 다음이 필요한 LLM 에이전트에 특히 유용합니다:

사용 가능한 프로젝트와 실행을 확인
Query metric values programmatically
get snapshot 또는 get metric --around를 사용하여 알림 주변의 메트릭을 검사합니다
구조화된 명령으로 처리되지 않는 경우를 위해 직접 SQL을 실행합니다
서버를 시작하지 않고 요약 가져오기
추가 처리를 위해 구조화된 JSON 출력을 파싱합니다

자동화 스크립트

이 명령어는 셸 스크립트 및 자동화 파이프라인에서 사용할 수 있습니다:

#!/bin/bash
PROJECT="my-project"
RUN="my-run"

# Get the latest loss value
LATEST_LOSS=$(trackio get metric --project "$PROJECT" --run "$RUN" --metric "loss" --json | jq -r '.values[-1].value')
echo "Latest loss: $LATEST_LOSS"

다른 도구와의 통합

JSON 출력 형식은 다른 도구와의 통합을 쉽게 만들어 줍니다:

# Pipe to jq for filtering
trackio list runs --project "my-project" --json | jq '.runs[] | select(startswith("train"))'

# Export to file
trackio get run --project "my-project" --run "my-run" --json > run_summary.json

Update on GitHub