Команды CLI

Trackio предоставляет комплексный набор команд CLI, позволяющих запрашивать информацию о проектах, запусках, метриках и Spaces без необходимости запуска MCP-сервера. По умолчанию команды работают с локальными данными, а при указании --space — с удалённым HF Space. Это особенно полезно для LLM-агентов и скриптов автоматизации. Благодаря структурированному JSON-выводу и программному доступу ко всем данным экспериментов, Trackio спроектирован для поддержки автономных ML-экспериментов, выполняемых LLM.

Запрос удалённых Spaces

Все команды list, get и query, которые читают данные дашборда, поддерживают запрос к удалённому Hugging Face Space вместо локальных данных. Передайте флаг --space с идентификатором Space или полным URL:

# 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

Для частных 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. Используйте trackio list spaces, чтобы найти дашборды Trackio на Hugging Face Hub, а затем передайте один из этих идентификаторов Space в команды, например trackio list projects --space username/my-space.

Команды реестра

Создайте реестр и, при необходимости, определите типизированную коллекцию перед добавлением в неё элементов:

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

Все команды реестра принимают --bucket-id org/bucket для реестра на основе bucket и --json для структурированного вывода. --alias можно указывать многократно. Цели можно записывать в виде models/churn-model или registry-models/churn-model.

Команда link разрешает project/artifact:version-or-alias из локальных данных Trackio; если опустить суффикс, будет разрешено latest. Публикация артефакта, который существует только на удалённом Space, по-прежнему выполняется через Python API, чтобы Trackio мог зафиксировать координаты удалённого хранилища источника.

Команда синхронизации

Загрузка локального проекта в Space на Hugging Face:

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

Разверните как статическое пространство (чтение из HF Bucket, сервер не требуется):

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

Статические Spaces предоставляют данные непосредственно из браузера и поэтому требуют публичные данные снапшота. --sdk static --private не поддерживается; для частных дашбордов используйте SDK Gradio по умолчанию.

Синхронизируйте все проекты, содержащие несинхронизированные данные, с их настроенными Spaces:

trackio sync --all

Команда Freeze

Создайте статический снимок Space с правами только на чтение из работающего Gradio Space:

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

Укажите пользовательское пространство назначения:

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

Примечание: Исходный ресурс должен представлять собой Gradio Space с подключённым бакетом по пути /data. Если целевой Space уже существует и не является статическим Space Trackio, команда freeze отклонит попытку перезаписи. Замороженный Space представляет собой снимок. Метрики, синхронизированные с исходным Gradio Space после этого, не появятся в замороженном статическом Space, если не запустить freeze повторно. Статические замороженные снимки требуют публичного доступа к данным в целевом Space, поэтому trackio freeze --private не поддерживается.

Bump

Обновите существующее пространство Trackio до версии Trackio, установленной локально:

trackio bump username/my-space

trackio bump --space username/my-space выполняет то же самое.

Space приостанавливается на время обновления, поэтому задачи обучения продолжают писать логи в папку inbox бакета Space. Его базы данных резервируются в trackio-backups/ в том же бакете, его Trackio pin обновляется, и он перезапускается, чтобы новая версия перенесла данные. Если обновлённый Space не запускается или сообщает о меньшем количестве строк, чем раньше, резервная копия и предыдущие файлы Space восстанавливаются.

Чтобы не трогать исходный Space, скопируйте его и его bucket в новый Space, работающий на локальной версии:

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

Примечание: bump поддерживает Gradio Spaces, работающие с Trackio версии 0.21.0 или новее, с подключённым хранилищем (bucket) по пути /data, и никогда не выполняет понижение версии Space. В более старых Spaces данные хранились в Hugging Face Dataset, а не в bucket.

Команды списка

Список всех проектов

Список всех доступных проектов:

trackio list projects

Вывод в формате JSON:

trackio list projects --json

Список пространств Trackio

Список Spaces с панелью Trackio, принадлежащих вашему аккаунту Hugging Face и организациям:

trackio list spaces

Вывод в формате JSON:

trackio list spaces --json

Список пространств Trackio в пространстве имён конкретного пользователя или организации:

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

Список метрик для запуска

Список всех метрик, отслеживаемых в конкретном запуске:

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

Вывод в формате JSON:

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

Список системных метрик для запуска

Список всех системных метрик (например, метрик GPU) для конкретного запуска:

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

Вывод в формате JSON:

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

Список отчетов

Список markdown-отчётов в проекте (по всем запускам):

trackio list reports --project "my-project"

Список markdown-отчётов для конкретного запуска:

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

Вывод в формате JSON:

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

Список трассировок

Список 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"

Поиск совпадает с содержимым сообщения, метаданными трассировки, а также с именем, типом, моделью, статусом и ошибкой каждого span. Управление порядком и пагинацией:

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 включает сводку summary по каждому трассированию.

Получить команды

Получить трассировку

Показать один трасс с полным деревом выполнения:

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 принимает короткий id, выводимый командой trackio list traces, или полный сохранённый id. Добавьте --json, чтобы получить полный трасс, включая входные и выходные данные span.

Получить сводку по трассировке

Сгруппируйте все span по имени операции, чтобы увидеть, где сосредоточены задержка, токены и стоимость, а также какие операции завершаются с ошибкой:

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. Для данных, не охваченных сводкой, напрямую запросите таблицу traces с помощью trackio query project — spans является столбцом JSON, поэтому json_each работает.

Получить сводку проекта

Получите подробное резюме проекта, включая количество запусков и недавнюю активность:

trackio get project --project "my-project"

Вывод в формате JSON:

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

Сводка включает:

• Название проекта
• Количество запусков
• Список всех запусков
• Последняя активность (максимальный шаг по всем запускам)

Получить сводку запуска

Получите подробное резюме конкретного запуска, включая метрики и конфигурацию:

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

Вывод в формате JSON:

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

Сводка включает:

• Имена проектов и запусков
• Количество записей журнала
• Последний шаг
• Список всех метрик
• Конфигурация запуска (без внутренних полей)

Получение значений метрик

Получить все значения для конкретного метрики в запуске:

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

Вывод в формате JSON:

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

Вывод включает:

• Номер шага
• Метка времени
• Значение метрики

Фильтрация по шагу или времени

Вы можете отфильтровать значения метрик по конкретному шагу или по окну вокруг шага/метки времени. Это полезно для анализа метрик в момент срабатывания оповещения.

# 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

Получить снимок метрик

Получите все метрики в момент или вблизи шага или временной метки одним вызовом. Это самый быстрый способ для агента понять состояние запуска в конкретный момент — например, сразу после срабатывания оповещения.

# 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

Получить содержимое отчета

Вывод записей отчёта в формате Markdown для конкретного имени отчёта в запуске:

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 query, когда вам нужен универсальный SQL-запрос только для чтения, который не покрывается командами trackio list или trackio get.

Выполнение запроса к базе данных проекта

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 см. в разделе Схема хранения и прямые запросы.

Форматы вывода

Все команды list, get и query поддерживают два формата вывода:

1. Человекочитаемый (по умолчанию): Форматированный текстовый вывод, подходящий для просмотра в терминале
2. JSON (с флагом --json): структурированный вывод в формате JSON, пригодный для программного использования

Обработка ошибок

Команды CLI включают комплексную валидацию и обработку ошибок:

• Если проект не существует, отображается сообщение об ошибке
• Если запуск не существует в проекте, отображается сообщение об ошибке
• Если метрика отсутствует в запуске, отображается сообщение об ошибке
• Если отчёт отсутствует в запуске, отображается сообщение об ошибке
• Если запрос не является только для чтения, CLI завершается с ошибкой

Все ошибки записываются в stderr, а команда завершается с ненулевым кодом выхода.

Пример рабочего процесса

Ниже приведена типичная последовательность действий для работы с вашими данными 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:

# 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, которым необходимо:

• Ознакомьтесь с доступными проектами и запусками
• Получение значений метрик программно
• Просмотрите метрики вокруг предупреждения с помощью 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