Add remote HF Space support to CLI (#445)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

Author: 3 people

.agents/skills/trackio/SKILL.md

@@ -53,6 +53,8 @@ Use the `trackio` command to query logged metrics and alerts:
 
 **Key concept**: Add `--json` for programmatic output suitable for automation and LLM agents.
 
+**Remote Spaces**: Add `--space <space_id_or_url>` to any `list`/`get` command to query a remote HF Space instead of local data. Use `--hf-token` for private Spaces.
+
 → See [retrieving_metrics.md](retrieving_metrics.md) for all commands, workflows, and JSON output formats.
 
 ## Minimal Logging Setup
@@ -71,6 +73,9 @@ trackio.finish()
 ```bash
 trackio list projects --json
 trackio get metric --project my-project --run my-run --metric loss --json
+
+# Query a remote Space
+trackio list projects --space username/my-space --json
 ```
 
 ## Autonomous ML Experiment Workflow

.agents/skills/trackio/retrieving_metrics.md

@@ -1,6 +1,6 @@
 # Retrieving Metrics with Trackio CLI
 
-The `trackio` CLI provides direct terminal access to query Trackio experiment tracking data locally without needing to start the MCP server.
+The `trackio` CLI provides direct terminal access to query Trackio experiment tracking data without needing to start the MCP server. Commands work against local data by default, or against a remote HF Space when `--space` is provided.
 
 ## Quick Command Reference
 
@@ -18,6 +18,7 @@ The `trackio` CLI provides direct terminal access to query Trackio experiment tr
 | Get metric around step | `trackio get metric ... --metric <name> --around <N> --window <W>` |
 | Get all metrics snapshot | `trackio get snapshot --project <name> --run <name> --step <N>` |
 | Get system metrics | `trackio get system-metric --project <name> --run <name>` |
+| Query remote Space | `trackio list projects --space <space_id_or_url>` |
 | Show dashboard | `trackio show [--project <name>]` |
 | Sync to Space | `trackio sync --project <name> --space-id <space_id>` |
 
@@ -68,6 +69,17 @@ trackio get system-metric --project <name> --run <name> --metric <name>  # Speci
 trackio get system-metric --project <name> --run <name> --json
 ```
 
+### Remote Space Queries
+
+All `list` and `get` commands support querying a remote HF Space with `--space`:
+
+```bash
+trackio list projects --space user/my-space              # Space ID
+trackio list projects --space https://user-my-space.hf.space  # Space URL
+trackio get metric --project <name> --run <name> --metric loss --space user/my-space
+trackio list projects --space user/private-space --hf-token hf_xxx  # Private Space
+```
+
 ### Dashboard Commands
 
 ```bash
@@ -185,6 +197,8 @@ All errors exit with non-zero status code and write to stderr.
 - `--run`: Run name (required for run-specific commands)
 - `--metric`: Metric name (required for metric-specific commands)
 - `--json`: Output in JSON format instead of human-readable
+- `--space`: HF Space ID (e.g. `user/space`) or Space URL to query remotely (for `list`/`get` commands)
+- `--hf-token`: HF token for accessing private Spaces (for `list`/`get` commands with `--space`)
 - `--step`: Exact step filter (for `get metric`, `get snapshot`)
 - `--around`: Center step for window filter (for `get metric`, `get snapshot`)
 - `--at-time`: Center ISO timestamp for window filter (for `get metric`, `get snapshot`)

.changeset/calm-suits-end.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Add remote HF Space support to CLI

autonomous-experiments/01_finding_the_best_learning_rate/train_nanogpt.py

@@ -43,6 +43,7 @@
 import torch
 import torch.nn as nn
 import torch.nn.functional as F
+
 import trackio
 
 # =====================================================================
@@ -206,7 +207,9 @@ class Muon(torch.optim.Optimizer):
     """
 
     def __init__(self, params, lr=0.02, momentum=0.95, weight_decay=0.0, ns_steps=5):
-        defaults = dict(lr=lr, momentum=momentum, weight_decay=weight_decay, ns_steps=ns_steps)
+        defaults = dict(
+            lr=lr, momentum=momentum, weight_decay=weight_decay, ns_steps=ns_steps
+        )
         super().__init__(params, defaults)
 
     @torch.no_grad()
@@ -279,7 +282,9 @@ def _load_token_shard(path):
         header = np.memmap(path, dtype=np.int32, mode="r", shape=(256,))
         if int(header[0]) == 20240520:
             num_tokens = int(header[2])
-            return np.memmap(path, dtype=np.uint16, mode="r", offset=256 * 4, shape=(num_tokens,))
+            return np.memmap(
+                path, dtype=np.uint16, mode="r", offset=256 * 4, shape=(num_tokens,)
+            )
         return np.memmap(path, dtype=np.uint16, mode="r")
 
     def __init__(self, data_dir, split, batch_size, seq_len, device, vocab_size):
@@ -298,7 +303,9 @@ def __init__(self, data_dir, split, batch_size, seq_len, device, vocab_size):
         total_tokens = sum(len(s) for s in self.shards)
         print(f"  {split}: {len(files)} shard(s), {total_tokens / 1e6:.0f}M tokens")
 
-        sample_tokens = np.concatenate([s[: min(4096, len(s))] for s in self.shards[:2]])
+        sample_tokens = np.concatenate(
+            [s[: min(4096, len(s))] for s in self.shards[:2]]
+        )
         sample_max = int(sample_tokens.max()) if len(sample_tokens) > 0 else -1
         assert sample_max < self.vocab_size, (
             f"Token id {sample_max} exceeds vocab_size={self.vocab_size}. "
@@ -456,9 +463,7 @@ def set_lr(step):
 def main():
     import argparse
 
-    parser = argparse.ArgumentParser(
-        description="Minimal NanoGPT training on FineWeb"
-    )
+    parser = argparse.ArgumentParser(description="Minimal NanoGPT training on FineWeb")
 
     parser.add_argument(
         "--optimizer",
@@ -467,9 +472,13 @@ def main():
         choices=["muon", "adamw"],
         help="Optimizer: muon (Muon+AdamW) or adamw (pure AdamW)",
     )
-    parser.add_argument("--learning_rate", type=float, default=None,
-                        help="Primary learning rate. Overrides --adam_lr for adamw, "
-                             "or both --muon_lr and --adam_lr (scaled) for muon.")
+    parser.add_argument(
+        "--learning_rate",
+        type=float,
+        default=None,
+        help="Primary learning rate. Overrides --adam_lr for adamw, "
+        "or both --muon_lr and --adam_lr (scaled) for muon.",
+    )
     parser.add_argument("--muon_lr", type=float, default=0.02)
     parser.add_argument("--adam_lr", type=float, default=6e-4)
     parser.add_argument("--weight_decay", type=float, default=0.01)
@@ -495,8 +504,12 @@ def main():
     parser.add_argument("--log_interval", type=int, default=10)
     parser.add_argument("--heartbeat_seconds", type=int, default=30)
     parser.add_argument("--seed", type=int, default=42)
-    parser.add_argument("--run_name", type=str, default=None,
-                        help="Override the auto-generated Trackio run name.")
+    parser.add_argument(
+        "--run_name",
+        type=str,
+        default=None,
+        help="Override the auto-generated Trackio run name.",
+    )
 
     args = parser.parse_args()
 
@@ -580,8 +593,10 @@ def main():
     optimizers, set_lr = build_optimizers(model, args)
 
     tokens_per_step = args.batch_size * args.seq_len * args.grad_accum_steps
-    print(f"\nTraining:")
-    print(f"  Batch size: {args.batch_size} x {args.grad_accum_steps} accum = {args.batch_size * args.grad_accum_steps} effective")
+    print("\nTraining:")
+    print(
+        f"  Batch size: {args.batch_size} x {args.grad_accum_steps} accum = {args.batch_size * args.grad_accum_steps} effective"
+    )
     print(f"  Sequence length: {args.seq_len}")
     print(f"  Tokens/step: {tokens_per_step:,}")
     print(f"  Max steps: {args.max_steps}")
@@ -621,17 +636,28 @@ def main():
             dt = time.time() - t0
             tokens_seen = (step + 1) * tokens_per_step
             tps = tokens_seen / dt if dt > 0 else 0
-            trackio.log({"train_loss": loss_accum, "lr": current_lr, "tok_per_sec": tps, "step": step})
+            trackio.log(
+                {
+                    "train_loss": loss_accum,
+                    "lr": current_lr,
+                    "tok_per_sec": tps,
+                    "step": step,
+                }
+            )
             last_heartbeat_t = time.time()
-        elif args.heartbeat_seconds > 0 and (time.time() - last_heartbeat_t) >= args.heartbeat_seconds:
+        elif (
+            args.heartbeat_seconds > 0
+            and (time.time() - last_heartbeat_t) >= args.heartbeat_seconds
+        ):
             dt = time.time() - t0
-            pct = (step + 1) / args.max_steps * 100
             last_heartbeat_t = time.time()
 
         if step > 0 and step % args.eval_interval == 0:
             val_loss = evaluate(model, val_loader, args.eval_steps)
             best_val_loss = min(best_val_loss, val_loss)
-            trackio.log({"val_loss": val_loss, "best_val_loss": best_val_loss, "step": step})
+            trackio.log(
+                {"val_loss": val_loss, "best_val_loss": best_val_loss, "step": step}
+            )
             if prev_val_loss is not None and val_loss > prev_val_loss:
                 trackio.alert(
                     title="Val loss increasing",
@@ -656,7 +682,14 @@ def main():
 | Total tokens | {total_tokens / 1e6:.0f}M |
 | Throughput | {total_tokens / total_time / 1e3:.1f}K tok/s |
 """)
-    trackio.log({"val_loss": val_loss, "best_val_loss": best_val_loss, "step": args.max_steps, "report": report})
+    trackio.log(
+        {
+            "val_loss": val_loss,
+            "best_val_loss": best_val_loss,
+            "step": args.max_steps,
+            "report": report,
+        }
+    )
 
     trackio.finish()
 

autonomous-experiments/README.md

@@ -0,0 +1,3 @@
+# Autonomous Experiments
+
+This directory contains scripts and prompt files that can be provided to coding agents (for example, Claude Code) to run autonomous machine learning experiments.

docs/source/cli_commands.md

@@ -1,6 +1,29 @@
 # CLI Commands
 
-Trackio provides a comprehensive set of CLI commands that enable you to query project, run, and metric information locally without needing to start the MCP server. This is particularly useful for LLM agents and automation scripts. With structured JSON output and programmatic access to all experiment data, Trackio is designed to support autonomous ML experiments run by LLMs.
+Trackio provides a comprehensive set of CLI commands that enable you to query project, run, and metric information without needing to start the MCP server. Commands work against local data by default, or against a remote HF Space when `--space` is provided. This is particularly useful for LLM agents and automation scripts. With structured JSON output and programmatic access to all experiment data, Trackio is designed to support autonomous ML experiments run by LLMs.
+
+## Querying Remote Spaces
+
+All `list` and `get` commands support querying a remote Hugging Face Space instead of local data. Pass the `--space` flag with either a Space ID or full URL:
+
+```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 command
+trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space
+```
+
+For private Spaces, pass `--hf-token` or ensure you are logged in via `huggingface-cli login`:
+
+```sh
+trackio list projects --space username/private-space --hf-token hf_xxxxx
+```
+
+> **Note:** The `show`, `status`, `sync`, and `skills` commands are local-only and do not support `--space`.
 
 ## List Commands
 
@@ -293,6 +316,18 @@ trackio list reports --project "my-project" --run "my-run"
 trackio get report --project "my-project" --run "my-run" --report "training_report"
 ```
 
+### Querying a Remote Space
+
+The same workflow works against a remote Space — just add `--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
+```
+
 ## Use Cases
 
 ### LLM Agents

tests/e2e-spaces/test_cli_remote.py

@@ -0,0 +1,52 @@
+import json
+import secrets
+import subprocess
+
+
+def test_cli_remote_list_and_get(test_space_id):
+    import trackio
+
+    project_name = f"test_cli_remote_{secrets.token_urlsafe(8)}"
+    run_name = "cli_run"
+
+    trackio.init(project=project_name, name=run_name, space_id=test_space_id)
+    trackio.log({"loss": 0.5, "acc": 0.8})
+    trackio.log({"loss": 0.3, "acc": 0.9})
+    trackio.finish()
+
+    def cli(*args):
+        result = subprocess.run(
+            ["trackio", *args, "--space", test_space_id, "--json"],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, f"CLI failed: {result.stderr}"
+        return json.loads(result.stdout)
+
+    projects = cli("list", "projects")
+    assert project_name in projects["projects"]
+
+    runs = cli("list", "runs", "--project", project_name)
+    assert run_name in runs["runs"]
+
+    metrics = cli("list", "metrics", "--project", project_name, "--run", run_name)
+    assert "loss" in metrics["metrics"]
+    assert "acc" in metrics["metrics"]
+
+    values = cli(
+        "get",
+        "metric",
+        "--project",
+        project_name,
+        "--run",
+        run_name,
+        "--metric",
+        "loss",
+    )
+    assert len(values["values"]) == 2
+    assert values["values"][0]["value"] == 0.5
+    assert values["values"][1]["value"] == 0.3
+
+    summary = cli("get", "run", "--project", project_name, "--run", run_name)
+    assert summary["num_logs"] == 2
+    assert "loss" in summary["metrics"]