Comandos de CLI

Trackio ofrece un conjunto completo de comandos de CLI que te permiten consultar información de proyectos, ejecuciones, métricas y Spaces sin necesidad de iniciar el servidor MCP. Los comandos funcionan con datos locales de forma predeterminada, o con un Space remoto de HF cuando se proporciona --space. Esto resulta especialmente útil para agentes de LLM y scripts de automatización. Con salida JSON estructurada y acceso programático a todos los datos de experimentos, Trackio está diseñado para soportar experimentos de ML autónomos ejecutados por LLMs.

Consultar espacios remotos

Todos los comandos list, get y query que leen datos del panel de control admiten consultar un Space remoto de Hugging Face en lugar de datos locales. Pasa la bandera --space con un ID de Space o una URL completa:

# 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

Para los Spaces privados, pasa --hf-token o asegúrate de que has iniciado sesión mediante huggingface-cli login:

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

Nota: Los comandos show, status, sync, freeze, skills, registry y list spaces no admiten --space. Utilice trackio list spaces para descubrir los paneles de Trackio en Hugging Face Hub y, a continuación, pase uno de esos IDs de Space a comandos como trackio list projects --space username/my-space.

Comandos del registro

Cree un registro y, cuando sea útil, defina una colección con tipos antes de vincular en ella:

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

Enlazar una versión de artefacto local, promover una versión de colección moviendo un alias o desvincular una versión:

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

Inspeccionar colecciones y su historial de auditoría:

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

Todos los comandos del registro aceptan --bucket-id org/bucket para un registro basado en un bucket y --json para una salida estructurada. --alias se puede repetir. Los destinos pueden escribirse como models/churn-model o registry-models/churn-model.

El comando link resuelve project/artifact:version-or-alias a partir de los datos locales de Trackio; omita el sufijo para resolver latest. Publicar un artefacto que solo existe en un Space remoto sigue utilizando la API de Python para que Trackio pueda registrar las coordenadas de almacenamiento remoto de la fuente.

Comando de sincronización

Subir un proyecto local a un Space de Hugging Face:

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

Despliega como un Space estático (lee desde un HF Bucket, no se necesita servidor):

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

Los espacios estáticos sirven datos directamente desde el navegador y, por lo tanto, requieren datos de instantáneas públicos. --sdk static --private no está admitido; use el SDK de Gradio predeterminado para los paneles privados.

Sincroniza todos los proyectos que tienen datos sin sincronizar con sus Spaces configurados:

trackio sync --all

Comando Freeze

Crea una instantánea estática de solo lectura de un Space de Gradio en vivo:

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

Especifica un Space de destino personalizado:

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

Nota: La fuente debe ser un Gradio Space con un bucket montado en /data. Si el Space de destino ya existe y no es un Space estático de Trackio, freeze se negará a sobrescribirlo. El Space congelado es una instantánea. Las métricas sincronizadas posteriormente con el Gradio Space original no aparecerán en el Space estático congelado a menos que vuelvas a ejecutar freeze. Las instantáneas estáticas congeladas requieren datos de destino públicos, por lo que trackio freeze --private no está admitido.

Bump

Actualice un espacio de Trackio existente a la versión de Trackio instalada localmente:

trackio bump username/my-space

trackio bump --space username/my-space hace lo mismo.

El Space se pausa mientras se actualiza, por lo que los trabajos de entrenamiento siguen registrando en la bandeja de entrada del bucket del Space. Sus bases de datos se copian de seguridad en trackio-backups/ dentro del mismo bucket, se actualiza el pin de Trackio y se reinicia para que la nueva versión migre los datos. Si el Space actualizado no inicia o informa de menos filas que antes, se restauran la copia de seguridad y los archivos del Space anterior.

Para mantener el Space original intacto, cópialo junto con su bucket a un nuevo Space que ejecute la versión local en su lugar:

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

Nota: bump admite Gradio Spaces que ejecutan Trackio 0.21.0 o una versión posterior con un bucket montado en /data, y nunca realiza una degradación de un Space. Los Spaces antiguos almacenaban sus datos en un Dataset de Hugging Face en lugar de en un bucket.

Comandos de lista

Listar todos los proyectos

Listar todos los proyectos disponibles:

trackio list projects

Salida en formato JSON:

trackio list projects --json

Listar espacios de Trackio

Listar los espacios del panel de Trackio que pertenecen a tu cuenta y organizaciones de Hugging Face:

trackio list spaces

Salida en formato JSON:

trackio list spaces --json

Listar los espacios de Trackio bajo un espacio de nombres de usuario u organización específico:

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

Limitar el número de Spaces devueltos:

trackio list spaces --limit 10

Para los Spaces privados, pasa --hf-token o asegúrate de que has iniciado sesión mediante huggingface-cli login.

Listar ejecuciones de un proyecto

Listar todas las ejecuciones en un proyecto específico:

trackio list runs --project "my-project"

Salida en formato JSON:

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

Listar métricas de una ejecución

Listar todas las métricas registradas en una ejecución específica:

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

Salida en formato JSON:

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

Listar las métricas del sistema para una ejecución

Liste todas las métricas del sistema (p. ej., métricas de GPU) para una ejecución específica:

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

Salida en formato JSON:

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

Listar informes

Listar los informes en Markdown de un proyecto (en todas las ejecuciones):

trackio list reports --project "my-project"

Listar los informes en Markdown para una ejecución específica:

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

Salida en formato JSON:

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

Listar trazas

Obtén la lista de traces (sesiones de agente o conversación) en todas las ejecuciones de un proyecto:

trackio list traces --project "my-project"

Cada fila muestra el estado de la traza, la latencia en tiempo real, el coste, el número de operaciones y la solicitud del usuario que la inició. Filtrar por ejecución, paso o texto:

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"

La búsqueda coincide con el contenido del mensaje, los metadatos de la traza y el nombre, tipo, modelo, estado y error de cada span. Controle el orden y la paginación:

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

--sort acepta request_time_desc (predeterminado), request_time_asc, step_asc y step_desc. Agregar --json incluye un resumen summary por traza.

Obtener comandos

Obtener Trace

Muestra una traza con su árbol de ejecución completo:

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 acepta el id corto que imprime trackio list traces o el id completo almacenado. Añade --json para obtener la traza completa, incluidos los datos de entrada y salida de los spans.

Obtener resumen de la traza

Agregue cada tramo por nombre de operación para ver dónde se concentran la latencia, los tokens y el costo, y qué operaciones fallan:

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

Restrinja a una sola ejecución con --run, o emita filas legibles por máquina con --json. Para lo que el resumen no cubra, consulte directamente la tabla traces con trackio query project — spans es una columna JSON, por lo que json_each funciona.

Obtener resumen del proyecto

Obtén un resumen detallado de un proyecto, incluido el número de ejecuciones y la actividad reciente:

trackio get project --project "my-project"

Salida en formato JSON:

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

El resumen incluye:

• Nombre del proyecto
• Número de ejecuciones
• Lista de todas las ejecuciones
• Última actividad (paso máximo en todas las ejecuciones)

Obtener resumen de ejecución

Obtén un resumen detallado de una ejecución específica, que incluya métricas y configuración:

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

Salida en formato JSON:

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

El resumen incluye:

• Nombres de proyecto y ejecución
• Número de entradas de registro
• Último paso
• Lista de todas las métricas
• Configuración de ejecución (excluyendo los campos internos)

Obtener valores de métricas

Obtenga todos los valores para una métrica específica en una ejecución:

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

Salida en formato JSON:

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

La salida incluye:

• Número de paso
• Marca de tiempo
• Valor de la métrica

Filtrado por paso o tiempo

Puede filtrar los valores de las métricas a un paso específico o a una ventana alrededor de un paso o marca de tiempo. Esto resulta útil para inspeccionar las métricas en el momento en que se activó una alerta.

# 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

Obtener instantánea de métricas

Obtén todos los métricas en o alrededor de un paso o marca de tiempo en una sola llamada. Esta es la forma más rápida para que un agente comprenda el estado de una ejecución en un punto específico, por ejemplo, justo cuando se activó una alerta.

# 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

Ejemplo de salida 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}
    ]
  }
}

Obtener valores de métricas del sistema

Obtén los valores de las métricas del sistema para una ejecución. Si no se proporciona el nombre de la métrica, se devuelven todas las métricas del sistema:

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

Salida en formato JSON:

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

Obtener el contenido del informe

Imprime las entradas de informe en formato markdown para un nombre de informe específico en una ejecución:

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

Salida en formato JSON:

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

Comando de consulta

Usa trackio query cuando necesites una consulta SQL de solo lectura genérica que no esté cubierta por trackio list o trackio get.

Ejecutar una consulta en una base de datos de proyecto

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"

Salida en formato JSON:

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

Consultar un Space remoto:

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

trackio query solo admite consultas de solo lectura SELECT, WITH y consultas seguras de esquema PRAGMA.

Ejemplos comunes de inspección de esquemas:

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

La respuesta incluye:

• project
• query
• columns
• rows
• row_count

Para el esquema completo de SQLite y parquet, consulte Storage Schema and Direct Queries.

Formatos de salida

Todos los comandos list, get y query admiten dos formatos de salida:

1. Legible por humanos (predeterminado): salida de texto con formato adecuada para verla en la terminal
2. JSON (con la bandera --json): salida JSON estructurada apta para consumo programático

Gestión de errores

Los comandos de la CLI incluyen una validación y un manejo de errores exhaustivos:

• Si un proyecto no existe, se muestra un mensaje de error
• Si una ejecución no existe en un proyecto, se muestra un mensaje de error
• Si una métrica no existe en una ejecución, se muestra un mensaje de error
• Si un informe no existe en una ejecución, se muestra un mensaje de error
• Si una consulta no es de solo lectura, la CLI finaliza con un error

Todos los errores se escriben en stderr y el comando finaliza con un código de salida no cero.

Flujo de trabajo de ejemplo

Este es un flujo de trabajo típico para explorar tus datos de 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"

Consultar un espacio remoto

El mismo flujo de trabajo funciona con un Space remoto: solo añade --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

Casos de uso

Agentes de LLM

Estos comandos de CLI son especialmente útiles para agentes de LLM que necesitan:

• Descubrir proyectos y ejecuciones disponibles
• Consultar valores de métricas de forma programática
• Inspecciona las métricas alrededor de una alerta con get snapshot o get metric --around
• Ejecutar SQL directo para los casos no cubiertos por los comandos estructurados
• Obtén resúmenes sin iniciar un servidor
• Analizar la salida JSON estructurada para un procesamiento adicional

Scripts de automatización

Puede usar estos comandos en scripts de shell y pipelines de automatización:

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

Integración con otras herramientas

El formato de salida JSON facilita la integración con otras herramientas:

# 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