Perintah CLI

Trackio menyediakan seperangkat perintah CLI yang komprehensif untuk memungkinkan Anda menanyakan informasi proyek, run, metrik, dan Space tanpa perlu memulai server MCP. Perintah bekerja terhadap data lokal secara default, atau terhadap HF Space jarak jauh ketika --space diberikan. Hal ini sangat berguna untuk agen LLM dan skrip otomasi. Dengan output JSON terstruktur dan akses programatik ke semua data eksperimen, Trackio dirancang untuk mendukung eksperimen ML otonom yang dijalankan oleh LLM.

Mengkueri Ruang Jauh

Semua perintah list, get, dan query yang membaca data dashboard mendukung pengkuerian Hugging Face Space jarak jauh alih-alih data lokal. Sampaikan flag --space dengan ID Space atau URL lengkap:

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

# Using a Space URL
trackio list projects --space https://huggingface.co/proxy/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

Untuk Spaces privat, berikan --hf-token atau pastikan Anda telah masuk melalui huggingface-cli login:

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

Catatan: Perintah show, status, sync, freeze, skills, registry, dan list spaces tidak mendukung --space. Gunakan trackio list spaces untuk menemukan dasbor Trackio di Hugging Face Hub, lalu berikan salah satu ID Space tersebut ke perintah seperti trackio list projects --space username/my-space.

Perintah Registry

Buat sebuah registry dan, jika berguna, definisikan koleksi bertipe sebelum menghubungkannya ke dalamnya:

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

Hubungkan versi artefak lokal, promosikan versi koleksi dengan memindahkan alias, atau batalkan tautan versi:

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

Periksa koleksi dan riwayat auditnya:

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

Semua perintah registry menerima --bucket-id org/bucket untuk registry yang didukung bucket dan --json untuk output terstruktur. --alias dapat diulang. Target dapat ditulis sebagai models/churn-model atau registry-models/churn-model.

Perintah link menyelesaikan project/artifact:version-or-alias dari data Trackio lokal; hilangkan akhiran untuk menyelesaikan latest. Penerbitan artefak yang hanya ada di Space jarak jauh tetap menggunakan API Python agar Trackio dapat merekam koordinat penyimpanan jarak jauh sumber.

Perintah Sinkronisasi

Unggah proyek lokal ke Hugging Face Space:

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

Deploy sebagai Space statis (membaca dari HF Bucket, tidak memerlukan server):

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

Static Spaces menyajikan data langsung dari browser dan oleh karena itu memerlukan data snapshot publik. --sdk static --private tidak didukung; gunakan Gradio SDK default untuk dasbor privat.

Sinkronkan semua proyek yang memiliki data yang belum disinkronkan ke Spaces yang dikonfigurasi:

trackio sync --all

Perintah Freeze

Buat snapshot Space statis yang hanya dapat dibaca dari Space Gradio yang aktif:

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

Tentukan Space tujuan kustom:

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

Catatan: Sumber harus berupa Gradio Space dengan bucket yang dipasang di /data. Jika Space tujuan sudah ada dan bukan Trackio static Space, freeze akan menolak untuk menimpanya. Space yang dibekukan adalah snapshot. Metrik yang disinkronkan kemudian ke Gradio Space asli tidak akan muncul di static Space yang dibekukan kecuali Anda menjalankan freeze lagi. Snapshot beku statis memerlukan data tujuan yang publik, sehingga trackio freeze --private tidak didukung.

Bump

Upgrade Trackio Space yang sudah ada ke versi Trackio yang diinstal secara lokal:

trackio bump username/my-space

trackio bump --space username/my-space melakukan hal yang sama.

Space dijeda selama proses upgrade, sehingga tugas pelatihan terus mencatat log ke kotak masuk bucket Space. Basis datanya dicadangkan ke trackio-backups/ di bucket yang sama, pin Trackio-nya diperbarui, dan Space di-restart agar versi baru dapat memigrasi data. Jika Space yang sudah di-upgrade gagal dimulai atau melaporkan jumlah baris yang lebih sedikit dari sebelumnya, cadangan dan file Space sebelumnya akan dipulihkan.

Untuk menjaga Space asli tetap utuh, salin Space tersebut beserta bucket-nya ke Space baru yang menjalankan versi lokal:

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

Catatan: bump mendukung Gradio Spaces yang menjalankan Trackio 0.21.0 atau lebih baru dengan bucket yang dipasang di /data, dan tidak pernah menurunkan versi sebuah Space. Spaces yang lebih lama menyimpan datanya dalam Hugging Face Dataset, bukan dalam bucket.

Perintah Daftar

Daftarkan Semua Proyek

Daftarkan semua proyek yang tersedia:

trackio list projects

Output dalam format JSON:

trackio list projects --json

Daftarkan Ruang Trackio

Daftar Spaces dashboard Trackio yang dimiliki oleh akun dan organisasi Hugging Face Anda:

trackio list spaces

Output dalam format JSON:

trackio list spaces --json

Daftarkan Trackio Spaces di bawah namespace pengguna atau organisasi tertentu:

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

Batasi jumlah Spaces yang dikembalikan:

trackio list spaces --limit 10

Untuk Spaces privat, berikan --hf-token atau pastikan Anda telah masuk melalui huggingface-cli login.

Daftarkan Jalankan untuk Proyek

Daftarkan semua run dalam proyek tertentu:

trackio list runs --project "my-project"

Output dalam format JSON:

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

Daftar Metrik untuk Sebuah Run

Daftarkan semua metrik yang dilacak dalam run tertentu:

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

Output dalam format JSON:

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

Daftarkan Metrik Sistem untuk Sebuah Run

Daftarkan semua metrik sistem (misalnya, metrik GPU) untuk run tertentu:

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

Output dalam format JSON:

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

Daftar Laporan

Daftarkan laporan markdown dalam sebuah proyek (di semua run):

trackio list reports --project "my-project"

Daftarkan laporan markdown untuk run tertentu:

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

Output dalam format JSON:

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

Daftar Jejak

Daftarkan traces (sesi agen atau percakapan) di semua run dalam sebuah proyek:

trackio list traces --project "my-project"

Setiap baris menampilkan status trace, latensi wall-clock, biaya, jumlah operasi, dan permintaan pengguna yang memulainya. Saring berdasarkan run, step, atau teks:

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"

Pencocokan pencarian mencakup isi pesan, metadata trace, serta nama, jenis, model, status, dan error dari setiap span. Kendalikan urutan dan paging:

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

--sort menerima request_time_desc (default), request_time_asc, step_asc, dan step_desc. Menambahkan --json menyertakan rollup summary per trace.

Dapatkan Perintah

Dapatkan Trace

Tampilkan satu trace dengan pohon eksekusinya secara lengkap:

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 menerima id pendek yang dicetak oleh trackio list traces atau id lengkap yang disimpan. Tambahkan --json untuk trace lengkap, termasuk input dan output span.

Dapatkan Ringkasan Trace

Gulung setiap span berdasarkan nama operasi untuk melihat di mana latensi, token, dan biaya berada, serta operasi mana yang gagal:

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

Batasi ke satu run dengan --run, atau outputkan baris yang dapat dibaca mesin dengan --json. Untuk hal-hal yang tidak dicakup oleh rollup, kueri tabel traces secara langsung dengan trackio query project — spans adalah kolom JSON, sehingga json_each berfungsi.

Dapatkan Ringkasan Proyek

Dapatkan ringkasan terperinci dari sebuah proyek, termasuk jumlah run dan aktivitas terbaru:

trackio get project --project "my-project"

Output dalam format JSON:

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

Ringkasan mencakup:

• Nama proyek
• Jumlah eksekusi
• Daftar semua run
• Aktivitas terakhir (langkah maksimum di semua run)

Dapatkan Ringkasan Run

Dapatkan ringkasan terperinci dari run tertentu, termasuk metrik dan konfigurasi:

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

Output dalam format JSON:

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

Ringkasan mencakup:

• Nama proyek dan eksekusi
• Jumlah entri log
• Langkah terakhir
• Daftar semua metrik
• Konfigurasi eksekusi (tidak termasuk bidang internal)

Dapatkan Nilai Metrik

Dapatkan semua nilai untuk metrik tertentu dalam sebuah run:

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

Output dalam format JSON:

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

Output mencakup:

• Nomor langkah
• Stempel waktu
• Nilai metrik

Filtering berdasarkan Langkah atau Waktu

Anda dapat memfilter nilai metrik ke langkah tertentu atau jendela di sekitar langkah/timestamp. Hal ini berguna untuk memeriksa metrik di sekitar waktu peringatan dipicu.

# 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

Dapatkan Snapshot Metrik

Dapatkan semua metrik pada atau sekitar langkah atau timestamp tertentu dalam satu panggilan. Ini adalah cara tercepat bagi agen untuk memahami status sebuah run pada titik tertentu — misalnya, tepat saat peringatan (alert) dipicu.

# 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

Contoh keluaran 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}
    ]
  }
}

Dapatkan Nilai Metrik Sistem

Dapatkan nilai metrik sistem untuk sebuah run. Jika nama metrik tidak diberikan, semua metrik sistem akan dikembalikan:

# 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"

Output dalam format JSON:

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

Dapatkan Konten Laporan

Cetak entri laporan markdown untuk nama laporan tertentu dalam sebuah run:

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

Output dalam format JSON:

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

Perintah Query

Gunakan trackio query ketika Anda memerlukan kueri SQL baca-saja yang bersifat umum dan belum tercakup oleh trackio list atau trackio get.

Jalankan Kueri terhadap Basis Data Proyek

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"

Output dalam format JSON:

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

Kueri Space jarak jauh:

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

trackio query hanya mendukung kueri SELECT, WITH, dan PRAGMA skema yang aman untuk dibaca saja.

Contoh pemeriksaan skema umum:

# 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"

Respons mencakup:

• project
• query
• columns
• rows
• row_count

Untuk tata letak SQLite dan parquet lengkap, lihat Skema Penyimpanan dan Kueri Langsung.

Format Output

Semua perintah list, get, dan query mendukung dua format output:

1. Bacaan manusia (default): Teks berformat yang cocok untuk ditampilkan di terminal
2. JSON (dengan flag --json): Output JSON terstruktur yang cocok untuk konsumsi programatik

Penanganan Kesalahan

Perintah CLI mencakup validasi dan penanganan kesalahan yang komprehensif:

• Jika proyek tidak ada, pesan kesalahan akan ditampilkan
• Jika sebuah run tidak ada dalam proyek, pesan kesalahan akan ditampilkan
• Jika sebuah metrik tidak ada dalam sebuah run, pesan kesalahan akan ditampilkan
• Jika laporan tidak ada dalam sebuah run, pesan kesalahan akan ditampilkan
• Jika sebuah query bukan read-only, CLI akan keluar dengan error

Semua kesalahan ditulis ke stderr dan perintah keluar dengan kode keluar non-nol.

Alur Kerja Contoh

Berikut adalah alur kerja yang umum untuk menjelajahi data Trackio Anda:

# 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"

Mengkueri Ruang Jauh

Alur kerja yang sama juga berfungsi untuk Space jarak jauh — cukup tambahkan --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

Kasus Penggunaan

Agen LLM

Perintah CLI ini sangat berguna untuk agen LLM yang perlu:

• Temukan proyek dan run yang tersedia
• Kueri nilai metrik secara programatik
• Periksa metrik di sekitar peringatan dengan get snapshot atau get metric --around
• Jalankan SQL langsung untuk kasus yang tidak tercakup oleh perintah terstruktur
• Dapatkan ringkasan tanpa memulai server
• Parse output JSON terstruktur untuk pemrosesan lebih lanjut

Skrip Otomasi

Anda dapat menggunakan perintah-perintah ini dalam skrip shell dan pipeline otomasi:

#!/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"

Integrasi dengan Alat Lain

Format output JSON memudahkan integrasi dengan alat lain:

# 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