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

```sh
# 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 Spaces privados, passe `--hf-token` ou verifique se você está conectado via `huggingface-cli login`:

```sh
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:

```sh
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:

```sh
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:

```sh
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 usa 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:

```sh
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):

```sh
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:

```sh
trackio sync --all
```

| Flag | Descrição |
|------|-------------|
| `--project` | O nome do projeto a ser sincronizado (obrigatório, a menos que `--all` seja usado) |
| `--space-id` | O ID do Space do HF para sincronizar (por exemplo, `username/space_id`). Se não for fornecido, usa o Space configurado anteriormente |
| `--all` | Sincronizar todos os projetos com dados não sincronizados |
| `--sdk` | `gradio` (padrão) para um servidor ao vivo, ou `static` para um Space somente leitura baseado em bucket |
| `--private` | Torne o Space privado ao criar um novo Space do Gradio. Não é suportado com `--sdk static` |
| `--force` | Sobrescrever o banco de dados existente sem solicitar confirmação |

## Comando Freeze

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

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

Especifique um Space de destino personalizado:

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

| Flag | Descrição |
|------|-------------|
| `--space-id` | ID do Espaço Gradio de origem (obrigatório) |
| `--project` | O projeto a ser congelado (obrigatório) |
| `--new-space-id` | O ID do Space estático de destino. O padrão é `{space_id}_static` |
| `--private` | Não suportado para snapshots estáticos congelados |

> **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 públicos de destino, 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:

```sh
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:

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

| Flag | Descrição |
|------|-------------|
| `space_id` | O Espaço Trackio para atualizar (obrigatório, ou passe-o com `--space`) |
| `--new-space` | Crie este Space a partir de uma cópia de `space_id` em vez de atualizar no local |
| `--new-bucket` | O bucket para `--new-space`. O padrão é `{new_space}-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:

```sh
trackio list projects
```

Saída em formato JSON:

```sh
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:

```sh
trackio list spaces
```

Saída em formato JSON:

```sh
trackio list spaces --json
```

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

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

Limite o número de Spaces retornados:

```sh
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:

```sh
trackio list runs --project "my-project"
```

Saída em formato JSON:

```sh
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:

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

Saída em formato JSON:

```sh
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:

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

Saída em formato JSON:

```sh
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):

```sh
trackio list reports --project "my-project"
```

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

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

Saída em formato JSON:

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

### Listar Trilhas

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

```sh
trackio list traces --project "my-project"
```

Cada linha exibe o status do rastro, 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:

```sh
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:

```sh
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 trilha.

## Obter Comandos

### Obter Trace

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

```sh
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:

```sh
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`](#query-command) — `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:

```sh
trackio get project --project "my-project"
```

Saída em formato JSON:

```sh
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:

```sh
trackio get run --project "my-project" --run "my-run"
```

Saída em formato JSON:

```sh
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:

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

Saída em formato JSON:

```sh
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.

```sh
# 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
```

| Flag | Descrição |
|------|-------------|
| `--step N` | Retorne a métrica exatamente no passo N |
| `--around N` | Retornar métricas em uma janela ao redor da etapa N |
| `--at-time T` | Retorna métricas em uma janela ao redor do timestamp ISO 8601 T |
| `--window W` | Tamanho da janela: ±passos para `--around`, ±segundos para `--at-time` (padrão: 10) |

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

```sh
# 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:

```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:

```sh
# 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:

```sh
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:

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

Saída em formato JSON:

```sh
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

```sh
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:

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

Consultar um Space remoto:

```sh
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:

```sh
# 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](./storage_schema).

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

```sh
# 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`:

```sh
# 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:

```sh
#!/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:

```sh
# 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
```