Comandos de CLI

Trackio fornece um conjunto abrangente de comandos de CLI que permitem consultar informações de projeto, execução, métrica e Space sem a necessidade de iniciar o servidor MCP. Os comandos funcionam com dados locais por padrão, ou com um Space remoto do HF quando --space é fornecido. Isso é particularmente útil para agentes de LLM e scripts de automação. Com saída JSON estruturada e acesso programático a todos os dados de experimento, o Trackio é projetado para suportar experimentos de ML autônomos executados por LLMs.

Consultando Espaços Remotos

Todos os comandos list, get e query que leem dados de dashboard suportam a consulta de um Space remoto do Hugging Face em vez de dados locais. Passe a flag --space com um ID de Space ou uma URL completa:

# 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

Para Spaces privados, passe --hf-token ou verifique se você está conectado via huggingface-cli login:

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

Observação: Os comandos show, status, sync, freeze, skills, registry e list spaces não suportam --space. Use trackio list spaces para descobrir os painéis do Trackio no Hugging Face Hub e, em seguida, passe um desses IDs de Space para comandos como trackio list projects --space username/my-space.

Comandos do Registro

Crie um registro e, quando útil, defina uma coleção tipada antes de vinculá-lo a ela:

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

Vincule uma versão de artefato local, promova uma versão de coleção movendo um alias ou desvincule uma versão:

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

Inspecione coleções e seu histórico de auditoria:

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

Todos os comandos de registro aceitam --bucket-id org/bucket para um registro baseado em bucket e --json para saída estruturada. --alias pode ser repetido. Os alvos podem ser escritos como models/churn-model ou registry-models/churn-model.

O comando link resolve project/artifact:version-or-alias a partir dos dados locais do Trackio; omita o sufixo para resolver latest. A publicação de um artefato que existe apenas em um Space remoto ainda utiliza a API em Python para que o Trackio possa registrar as coordenadas de armazenamento remoto da origem.

Comando de Sincronização

Envie um projeto local para um Space do Hugging Face:

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

Implante como um Space estático (lê de um Bucket do HF, sem necessidade de servidor):

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

Os Spaces estáticos servem dados diretamente do navegador e, portanto, exigem dados de snapshot públicos. --sdk static --private não é suportado; use o SDK Gradio padrão para dashboards privados.

Sincronize todos os projetos que possuem dados não sincronizados com seus Spaces configurados:

trackio sync --all

Comando Freeze

Crie um snapshot estático somente de leitura de um Space Gradio ao vivo:

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

Especifique um Space de destino personalizado:

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

Observação: A origem deve ser um Gradio Space com um bucket montado em /data. Se o Space de destino já existir e não for um Space estático do Trackio, o freeze recusará sobrescrevê-lo. O Space congelado é um instantâneo. Métricas sincronizadas posteriormente com o Gradio Space original não aparecerão no Space estático congelado, a menos que você execute o freeze novamente. Os instantâneos estáticos congelados exigem dados de destino públicos, portanto, o trackio freeze --private não é suportado.

Bump

Faça o upgrade de um Space do Trackio existente para a versão do Trackio instalada localmente:

trackio bump username/my-space

trackio bump --space username/my-space faz a mesma coisa.

O Space fica pausado durante o upgrade, portanto os jobs de treinamento continuam registrando logs na caixa de entrada do bucket do Space. Seus bancos de dados são copiados para trackio-backups/ no mesmo bucket, seu pin do Trackio é atualizado e ele é reiniciado para que a nova versão migre os dados. Se o Space atualizado falhar ao iniciar ou reportar menos linhas do que antes, o backup e os arquivos do Space anterior serão restaurados.

Para manter o Space original intacto, copie-o e seu bucket para um novo Space executando a versão local:

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

Observação: bump suporta Gradio Spaces executando Trackio 0.21.0 ou mais recente com um bucket montado em /data e nunca faz downgrade de um Space. Spaces mais antigos armazenavam seus dados em um Dataset do Hugging Face em vez de um bucket.

Comandos de Listagem

Listar Todos os Projetos

Liste todos os projetos disponíveis:

trackio list projects

Saída em formato JSON:

trackio list projects --json

Listar Espaços do Trackio

Liste os Spaces do painel do Trackio pertencentes à sua conta e às organizações do Hugging Face:

trackio list spaces

Saída em formato JSON:

trackio list spaces --json

Liste os Espaços do Trackio em um namespace de usuário ou organização específico:

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

Limite o número de Spaces retornados:

trackio list spaces --limit 10

Para Spaces privados, passe --hf-token ou verifique se você está conectado via huggingface-cli login.

Listar Execuções para um Projeto

Liste todas as execuções em um projeto específico:

trackio list runs --project "my-project"

Saída em formato JSON:

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

Listar métricas para uma execução

Liste todas as métricas rastreadas em uma execução específica:

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

Saída em formato JSON:

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

Listar métricas do sistema para uma execução

Liste todas as métricas do sistema (por exemplo, métricas de GPU) para uma execução específica:

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

Saída em formato JSON:

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

Listar Relatórios

Listar relatórios em Markdown em um projeto (entre todas as execuções):

trackio list reports --project "my-project"

Liste os relatórios em Markdown para uma execução específica:

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

Saída em formato JSON:

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

Listar Trilhas

Liste traces (sessões de agente ou de conversa) em todas as execuções de um projeto:

trackio list traces --project "my-project"

Cada linha exibe o status do trace, a latência em tempo real, o custo, a contagem de operações e a solicitação do usuário que o iniciou. Filtre por execução, etapa ou 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"

A pesquisa corresponde ao conteúdo da mensagem, aos metadados do rastro e ao nome, tipo, modelo, status e erro de cada span. Controle a ordenação e a paginação:

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

--sort aceita request_time_desc (padrão), request_time_asc, step_asc e step_desc. Adicionar --json inclui um resumo summary por trace.

Obter Comandos

Obter Trace

Exibir um trace com sua árvore de execução completa:

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 aceita o id curto impresso por trackio list traces ou o id completo armazenado. Adicione --json para obter o trace completo, incluindo entradas e saídas dos spans.

Obter Resumo do Rastreamento

Agregue cada span pelo nome da operação para ver onde estão a latência, os tokens e o custo, e quais operações falham:

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 uma única execução com --run ou emita linhas legíveis por máquina com --json. Para qualquer coisa que o rollup não cubra, consulte a tabela traces diretamente com trackio query project — spans é uma coluna JSON, então json_each funciona.

Obter Resumo do Projeto

Obtenha um resumo detalhado de um projeto, incluindo o número de execuções e a atividade recente:

trackio get project --project "my-project"

Saída em formato JSON:

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

O resumo inclui:

• Nome do projeto
• Número de execuções
• Lista de todas as execuções
• Última atividade (etapa máxima em todas as execuções)

Obter resumo da execução

Obtenha um resumo detalhado de uma execução específica, incluindo métricas e configuração:

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

Saída em formato JSON:

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

O resumo inclui:

• Nomes de projeto e execução
• Número de registros de log
• Última etapa
• Lista de todas as métricas
• Configuração de execução (excluindo campos internos)

Obter valores de métricas

Obtenha todos os valores para uma métrica específica em uma execução:

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

Saída em formato JSON:

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

A saída inclui:

• Número da etapa
• Carimbo de data e hora
• Valor da métrica

Filtrando por Etapa ou Tempo

Você pode filtrar os valores de métricas para um passo específico ou para uma janela ao redor de um passo/timestamp. Isso é útil para inspecionar as métricas no período em que um alerta foi disparado.

# 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

Obter instantâneo de métricas

Obtenha todos os métricas em torno de um passo ou timestamp em uma única chamada. Esta é a maneira mais rápida para um agente entender o estado de uma execução em um ponto específico — por exemplo, exatamente quando um alerta foi disparado.

# 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

Exemplo de saída 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}
    ]
  }
}

Obter valores de métricas do sistema

Obtém os valores das métricas de sistema para uma execução. Se nenhum nome de métrica for fornecido, todas as métricas de sistema serão retornadas:

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

Saída em formato JSON:

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

Obter o Conteúdo do Relatório

Imprima as entradas do relatório em Markdown para um nome de relatório específico em uma execução:

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

Saída em formato JSON:

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

Comando de Consulta

Use trackio query quando precisar de uma consulta SQL somente de leitura genérica que não seja coberta por trackio list ou trackio get.

Executar uma Consulta em um Banco de Dados de Projeto

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"

Saída em formato JSON:

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

Consultar um Space remoto:

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

trackio query suporta apenas consultas somente leitura SELECT, WITH e consultas seguras de esquema PRAGMA.

Exemplos comuns de inspeção de esquema:

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

A resposta inclui:

• project
• query
• columns
• rows
• row_count

Para o layout completo do SQLite e parquet, consulte o Esquema de Armazenamento e Consultas Diretas.

Formatos de Saída

Todos os comandos list, get e query suportam dois formatos de saída:

1. Legível por humanos (padrão): Saída de texto formatada adequada para visualização no terminal
2. JSON (com a flag --json): saída JSON estruturada adequada para consumo programático

Tratamento de Erros

Os comandos de CLI incluem validação abrangente e tratamento de erros:

• Se um projeto não existir, uma mensagem de erro será exibida
• Se uma execução não existir em um projeto, uma mensagem de erro é exibida
• Se uma métrica não existir em uma execução, uma mensagem de erro é exibida
• Se um relatório não existir em uma execução, uma mensagem de erro é exibida
• Se uma consulta não for somente leitura, o CLI encerra com um erro

Todos os erros são gravados no stderr e o comando é encerrado com um código de saída não nulo.

Fluxo de Trabalho de Exemplo

Aqui está um fluxo de trabalho típico para explorar seus dados do 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"

Consultando um Espaço Remoto

O mesmo fluxo de trabalho funciona contra um Space remoto — basta adicionar --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

Esses comandos de CLI são particularmente úteis para agentes de LLM que precisam:

• Descubra projetos e execuções disponíveis
• Consulte valores de métricas programaticamente
• Inspecione métricas em torno de um alerta com get snapshot ou get metric --around
• Execute SQL direto para casos não cobertos pelos comandos estruturados
• Obtenha resumos sem iniciar um servidor
• Analise a saída JSON estruturada para processamento adicional

Scripts de Automação

Você pode usar esses comandos em scripts de shell e pipelines de automação:

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

Integração com Outras Ferramentas

O formato de saída JSON facilita a integração com outras ferramentas:

# 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