Commandes CLI

Trackio fournit un ensemble complet de commandes CLI qui vous permettent d’interroger les informations relatives aux projets, aux exécutions, aux métriques et aux Spaces sans avoir à démarrer le serveur MCP. Les commandes fonctionnent par défaut sur les données locales, ou sur un Space HF distant lorsque --space est fourni. C’est particulièrement utile pour les agents LLM et les scripts d’automatisation. Grâce à une sortie JSON structurée et à un accès programmatique à toutes les données d’expérimentation, Trackio est conçu pour soutenir les expériences ML autonomes menées par des LLM.

Interroger des espaces distants

Toutes les commandes list, get et query qui lisent des données de tableau de bord permettent d’interroger un Space Hugging Face distant au lieu de données locales. Passez le drapeau --space avec un identifiant de Space ou une URL complète :

# 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

Pour les Spaces privés, passez --hf-token ou assurez-vous d’être connecté via huggingface-cli login :

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

Remarque : Les commandes show, status, sync, freeze, skills, registry et list spaces ne prennent pas en charge --space. Utilisez trackio list spaces pour découvrir les tableaux de bord Trackio sur le Hugging Face Hub, puis transmettez l'un de ces identifiants Space à des commandes telles que trackio list projects --space username/my-space.

Commandes du registre

Créez un registre et, si nécessaire, définissez une collection typée avant d’y lier des éléments :

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

Lier une version d’artefact local, promouvoir une version de collection en déplaçant un alias, ou délier une version :

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

Inspecter les collections et leur historique d’audit :

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

Toutes les commandes du registre acceptent --bucket-id org/bucket pour un registre adossé à un bucket et --json pour une sortie structurée. --alias est répétable. Les cibles peuvent être écrites sous la forme models/churn-model ou registry-models/churn-model.

La commande link résout project/artifact:version-or-alias à partir des données Trackio locales ; omettez le suffixe pour résoudre latest. La publication d’un artefact qui n’existe que sur un Space distant utilise toujours l’API Python afin que Trackio puisse enregistrer les coordonnées de stockage distant de la source.

Commande Sync

Téléverser un projet local sur un Space Hugging Face :

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

Déployer en tant que Space statique (lit depuis un Bucket HF, aucun serveur nécessaire) :

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

Les Static Spaces servent les données directement depuis le navigateur et nécessitent donc des données de snapshot publiques. --sdk static --private n'est pas pris en charge ; utilisez le SDK Gradio par défaut pour les tableaux de bord privés.

Synchronisez tous les projets qui ont des données non synchronisées vers leurs Spaces configurés :

trackio sync --all

Commande Freeze

Créer un instantané statique en lecture seule d'un Space Gradio en direct :

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

Spécifier un Space de destination personnalisé :

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

Remarque : la source doit être un Space Gradio avec un bucket monté sur /data. Si le Space de destination existe déjà et n'est pas un Space statique Trackio, freeze refusera de l'écraser. Le Space figé est un instantané. Les métriques synchronisées ultérieurement vers le Space Gradio d'origine n'apparaîtront pas dans le Space statique figé à moins de relancer freeze. Les instantanés statiques figés nécessitent des données de destination publiques, trackio freeze --private n'est donc pas pris en charge.

Bump

Mettre à niveau un Space Trackio existant vers la version de Trackio installée localement :

trackio bump username/my-space

trackio bump --space username/my-space fait la même chose.

L’Espace est en pause pendant sa mise à niveau, de sorte que les tâches d’entraînement continuent d’écrire leurs journaux dans la boîte d’entrée du bucket de l’Espace. Ses bases de données sont sauvegardées dans trackio-backups/ au sein du même bucket, son pin Trackio est mis à jour, puis il redémarre afin que la nouvelle version migre les données. Si l’Espace mis à niveau échoue au démarrage ou signale moins de lignes qu’auparavant, la sauvegarde et les fichiers de l’Espace précédent sont restaurés.

Pour laisser l’Space d’origine intact, copiez-le ainsi que son bucket dans un nouvel Space exécutant à la place la version locale :

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

Remarque : bump prend en charge les Gradio Spaces exécutant Trackio 0.21.0 ou une version ultérieure avec un bucket monté sur /data, et ne rétrograde jamais un Space. Les Spaces plus anciens stockaient leurs données dans un Hugging Face Dataset plutôt que dans un bucket.

Commandes de liste

Lister tous les projets

Lister tous les projets disponibles :

trackio list projects

Sortie au format JSON :

trackio list projects --json

Lister les espaces Trackio

Liste des Spaces du tableau de bord Trackio appartenant à votre compte Hugging Face et à vos organisations :

trackio list spaces

Sortie au format JSON :

trackio list spaces --json

Lister les espaces Trackio sous un espace de noms d’utilisateur ou d’organisation spécifique :

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

Limiter le nombre de Spaces retournés :

trackio list spaces --limit 10

Pour les Spaces privés, passez --hf-token ou assurez-vous d’être connecté via huggingface-cli login.

Liste des exécutions pour un projet

Lister toutes les exécutions d'un projet spécifique :

trackio list runs --project "my-project"

Sortie au format JSON :

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

Lister les métriques d'une exécution

Lister toutes les métriques suivies dans une exécution spécifique :

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

Sortie au format JSON :

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

Lister les métriques système d'une exécution

Lister toutes les métriques système (par exemple, les métriques GPU) pour une exécution spécifique :

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

Sortie au format JSON :

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

Liste des rapports

Lister les rapports Markdown d’un projet (sur l’ensemble des exécutions) :

trackio list reports --project "my-project"

Lister les rapports Markdown pour une exécution spécifique :

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

Sortie au format JSON :

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

Liste des traces

Lister les traces (sessions d’agent ou de conversation) de toutes les exécutions d’un projet :

trackio list traces --project "my-project"

Chaque ligne affiche l’état de la trace, la latence réelle, le coût, le nombre d’opérations et la requête utilisateur qui l’a initiée. Filtrez par exécution, étape ou texte :

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 recherche correspond au contenu du message, aux métadonnées de la trace et au nom, au type, au modèle, à l'état et à l'erreur de chaque span. Contrôlez l'ordre et la pagination :

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

--sort accepte request_time_desc (par défaut), request_time_asc, step_asc et step_desc. L’ajout de --json inclut un regroupement summary par trace.

Obtenir les commandes

Obtenir la trace

Afficher une trace avec son arbre d'exécution complet :

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 accepte l’identifiant court affiché par trackio list traces ou l’identifiant complet stocké. Ajoutez --json pour obtenir la trace complète, y compris les entrées et sorties des spans.

Obtenir le résumé de la trace

Regroupez chaque span par nom d'opération pour voir où se situent la latence, les jetons et le coût, et quelles opérations échouent :

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

Restreindre à une seule exécution avec --run, ou émettre des lignes lisibles par machine avec --json. Pour tout ce que le rollup ne couvre pas, interroger directement la table traces avec trackio query project — spans est une colonne JSON, donc json_each fonctionne.

Obtenir le résumé du projet

Obtenez un résumé détaillé d'un projet, y compris le nombre d'exécutions et l'activité récente :

trackio get project --project "my-project"

Sortie au format JSON :

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

Le résumé comprend :

• Nom du projet
• Nombre d'exécutions
• Liste de toutes les exécutions
• Dernière activité (étape maximale sur l'ensemble des exécutions)

Obtenir le résumé d'exécution

Obtenez un résumé détaillé d'une exécution spécifique, y compris les métriques et la configuration :

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

Sortie au format JSON :

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

Le résumé comprend :

• Noms de projet et d'exécution
• Nombre d'entrées de journal
• Dernière étape
• Liste de toutes les métriques
• Configuration d'exécution (à l'exception des champs internes)

Obtenir les valeurs des métriques

Obtenir toutes les valeurs pour une métrique spécifique dans une exécution :

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

Sortie au format JSON :

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

La sortie comprend :

• Numéro d'étape
• Horodatage
• Valeur de la métrique

Filtrage par étape ou par temps

Vous pouvez filtrer les valeurs des métriques pour une étape spécifique ou une fenêtre autour d'une étape/timestamp. Cela est utile pour inspecter les métriques autour du moment où une alerte a été déclenchée.

# 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

Obtenir un instantané des métriques

Obtenez toutes les métriques à un instant donné ou autour d'une étape ou d'un horodatage en un seul appel. C'est la méthode la plus rapide pour qu'un agent comprenne l'état d'une exécution à un point précis — par exemple, au moment exact où une alerte a été déclenchée.

# 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

Exemple de sortie 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}
    ]
  }
}

Obtenir les valeurs des métriques système

Récupérer les valeurs des métriques système pour une exécution. Si aucun nom de métrique n'est fourni, toutes les métriques système sont renvoyées :

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

Sortie au format JSON :

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

Obtenir le contenu du rapport

Afficher les entrées de rapport au format Markdown pour un nom de rapport spécifique dans une exécution :

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

Sortie au format JSON :

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

Commande de requête

Utilisez trackio query lorsque vous avez besoin d’une requête SQL en lecture seule générique qui n’est pas déjà couverte par trackio list ou trackio get.

Exécuter une requête sur une base de données de projet

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"

Sortie au format JSON :

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

Interroger un Space distant :

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

trackio query ne prend en charge que les requêtes en lecture seule SELECT, WITH et les requêtes PRAGMA de schéma sûres.

Exemples courants d'inspection de schéma :

# 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 réponse inclut :

• project
• query
• columns
• rows
• row_count

Pour la structure complète SQLite et parquet, consultez Storage Schema and Direct Queries.

Formats de sortie

Toutes les commandes list, get et query prennent en charge deux formats de sortie :

1. Lisible par un humain (par défaut) : sortie de texte mise en forme, adaptée à l’affichage dans un terminal
2. JSON (avec le drapeau --json) : sortie JSON structurée adaptée à une consommation programmatique

Gestion des erreurs

Les commandes CLI incluent une validation et une gestion des erreurs complètes :

• Si un projet n’existe pas, un message d’erreur est affiché
• Si une exécution n’existe pas dans un projet, un message d’erreur est affiché
• Si une métrique n’existe pas dans une exécution, un message d’erreur est affiché
• Si un rapport n’existe pas dans une exécution, un message d’erreur est affiché
• Si une requête n'est pas en lecture seule, le CLI se termine avec une erreur

Toutes les erreurs sont écrites sur stderr et la commande se termine avec un code de sortie non nul.

Exemple de flux de travail

Voici un flux de travail typique pour explorer vos données 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"

Interroger un espace distant

Le même flux de fonctionnement fonctionne avec un Space distant — il suffit d’ajouter --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

Cas d'utilisation

Agents LLM

Ces commandes CLI sont particulièrement utiles pour les agents LLM qui doivent :

• Découvrir les projets et les exécutions disponibles
• Interroger les valeurs des métriques de manière programmatique
• Inspecter les métriques autour d’une alerte avec get snapshot ou get metric --around
• Exécuter du SQL direct pour les cas non couverts par les commandes structurées
• Obtenir des résumés sans démarrer de serveur
• Analyser la sortie JSON structurée pour un traitement ultérieur

Scripts d'automatisation

Vous pouvez utiliser ces commandes dans des scripts shell et des pipelines d'automatisation :

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

Intégration avec d'autres outils

Le format de sortie JSON facilite l'intégration avec d'autres outils :

# 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