### Run Rust Quickstart

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Navigate to the trackio-rs directory and run the quickstart example using Cargo to log sample metrics.

```bash
cd trackio-rs && cargo run --example quickstart
```

--------------------------------

### Install Trackio Go Client

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-go/README.md

Install the trackio-go client using the go get command.

```bash
go get github.com/gradio-app/trackio/contrib/trackio-go
```

--------------------------------

### Example Workflow: Local Tracking and Syncing

Source: https://github.com/gradio-app/trackio/blob/main/README.md

This example demonstrates starting local tracking with `trackio.init()` and `trackio.log()`, finishing the local run with `trackio.finish()`, and then syncing the project to Hugging Face Spaces using `trackio.sync()`.

```python
import trackio

# Start tracking locally
trackio.init(project="my-project", config={"lr": 0.001})
trackio.log({"loss": 0.5})
trackio.finish()

# Later, sync to Spaces
trackio.sync(
    project="my-project",
    space_id="username/my-experiments",
    frontend_dir="./my-trackio-frontend",
)
```

--------------------------------

### Install Trackio with uv

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Use uv to install the Trackio library. Ensure uv is installed first.

```bash
uv pip install trackio
```

--------------------------------

### Install Trackio from Source with uv

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Clone the Trackio repository and install it using uv. This installs the package from the local source.

```bash
git clone https://github.com/gradio-app/trackio.git
cd trackio/
```

```sh
uv pip install .
```

--------------------------------

### Run Go Quickstart

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Execute the Go quickstart script to log sample metrics to your Trackio dashboard.

```bash
go run trackio-go/examples/quickstart
```

--------------------------------

### Run JavaScript Quickstart

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Execute the JavaScript quickstart script using Node.js to log sample metrics to your Trackio dashboard.

```bash
node trackio-js/examples/quickstart.mjs
```

--------------------------------

### Installation and Build

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-js/README.md

Install project dependencies and build the TypeScript client. These commands are necessary before running the client in your project.

```bash
npm install
npm run build
```

--------------------------------

### Clone and Install Trackio from Source with uv

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Clone the Trackio repository and install it using uv for development. This installs the package in editable mode.

```bash
git clone https://github.com/gradio-app/trackio.git
cd trackio/
```

```sh
uv pip install -e .
```

--------------------------------

### Install Trackio with uv

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Install the Trackio library using uv. Requires Python 3.10 or higher.

```bash
uv pip install trackio
```

--------------------------------

### Install Trackio from Source with pip

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Clone the Trackio repository and install it using pip. This installs the package from the local source.

```bash
git clone https://github.com/gradio-app/trackio.git
cd trackio/
```

```sh
pip install .
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Example JSON configuration for adding the Trackio MCP server to a client.

```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://127.0.0.1:7860/mcp/"
    }
  }
}
```

--------------------------------

### Install Trackio with pip

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Use pip to install the Trackio library. This is the standard Python package installer.

```bash
pip install trackio
```

--------------------------------

### Set Rust Environment Variables

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Set these environment variables before running the Rust quickstart example. Ensure TRACKIO_SERVER_URL points to your deployed dashboard.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="rs-quickstart"
export TRACKIO_RUN="rs-run-1"
```

--------------------------------

### Set Environment Variables and Run Example

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-rs/README.md

Before running the Rust example, set the necessary environment variables for the Trackio server URL, Hugging Face token, project name, and run name.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="rs-quickstart"
export TRACKIO_RUN="rs-run-1"

cargo run --example quickstart
```

--------------------------------

### Install with Development Dependencies

Source: https://github.com/gradio-app/trackio/blob/main/CLAUDE.md

Install the package in editable mode with development and tensorboard dependencies.

```bash
pip install -e .[dev,tensorboard]
```

--------------------------------

### Quickstart: Log Metrics via CLI

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-js/README.md

Set environment variables and run a Node.js script to log metrics. Ensure TRACKIO_SERVER_URL, HF_TOKEN, TRACKIO_PROJECT, and TRACKIO_RUN are configured.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="js-quickstart"
export TRACKIO_RUN="js-run-1"

node examples/quickstart.mjs
```

--------------------------------

### Install Trackio

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebook_integration.ipynb

Installs the Trackio library quietly. Use this at the beginning of your notebook to ensure Trackio is available.

```python
!pip install -q trackio
```

--------------------------------

### MCP Client Configuration Example

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

An example configuration snippet for clients that support streamable-HTTP MCP servers, showing how to register the Trackio MCP server.

```APIDOC
## MCP Client Configuration

To add Trackio to clients that support streamable-HTTP MCP servers, use a config like:

```json
{
  "mcpServers": {
    "trackio": {
      "url": "http://127.0.0.1:7860/mcp/"
    }
  }
}
```
```

--------------------------------

### Install Trackio with GPU Monitoring Dependencies

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Install Trackio with the optional 'gpu' extra to enable NVIDIA GPU monitoring.

```bash
pip install trackio[gpu]
```

--------------------------------

### Install Trackio

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

Install the Trackio library using pip. This command ensures you have the latest version.

```python
!pip install -Uq trackio
```

--------------------------------

### Fine-Tuning Example with Trackio

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/rapidfireai_integration.md

Run a fine-tuning experiment with Trackio tracking enabled. Ensure Trackio is enabled via environment variables before initializing the Experiment.

```python
import os
os.environ["RF_TRACKIO_ENABLED"] = "true"

from rapidfireai import Experiment
from rapidfireai.automl import RFGridSearch, RFModelConfig, RFLoraConfig, RFSFTConfig

experiment = Experiment(experiment_name="my-sft-experiment", mode="fit")

config = RFModelConfig(
    model_name="TinyLlama/TinyLlama-1.1B-Chat-v1.0",
    peft_config=RFLoraConfig(r=8, lora_alpha=16, target_modules=["q_proj", "v_proj"]),
    training_args=RFSFTConfig(
        learning_rate=1e-4,
        max_steps=128,
        logging_steps=2,
        eval_strategy="steps",
        eval_steps=4,
    ),
    model_type="causal_lm",
)

experiment.run_fit(
    RFGridSearch(configs=[config], trainer_type="SFT"),
    create_model_fn,
    train_dataset,
    eval_dataset,
    num_chunks=4
)
```

--------------------------------

### Launch Dashboard for All Projects

Source: https://github.com/gradio-app/trackio/blob/main/CLAUDE.md

Start the Trackio dashboard to view all tracked projects.

```bash
trackio show
```

--------------------------------

### Clone and Install Trackio from Source with pip

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Clone the Trackio repository and install it using pip for development. This installs the package in editable mode.

```bash
git clone https://github.com/gradio-app/trackio.git
cd trackio/
```

```sh
pip install -e .
```

--------------------------------

### Install Trackio with Development Dependencies

Source: https://github.com/gradio-app/trackio/blob/main/CONTRIBUTING.md

Install the package in editable mode with development and tensorboard dependencies.

```bash
pip install -e ".[dev,tensorboard]"
```

--------------------------------

### Integration: Export Run Summary to JSON File

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Example of redirecting the JSON output of `trackio get run` to a file for later use.

```sh
trackio get run --project "my-project" --run "my-run" --json > run_summary.json
```

--------------------------------

### Install Trackio with Apple Silicon GPU Monitoring Dependencies

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Install Trackio with the optional 'apple-gpu' extra for system and Apple Silicon GPU metrics.

```bash
pip install trackio[apple-gpu]
```

--------------------------------

### Install Trackio with pip

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Install the Trackio library using pip. Requires Python 3.10 or higher.

```bash
pip install trackio
```

--------------------------------

### Install Trackio with TensorBoard Import Dependencies

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/installation.md

Install Trackio with the optional 'tensorboard' extra to enable TensorBoard event file importing.

```bash
pip install trackio[tensorboard]
```

--------------------------------

### Install RapidFire AI

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/rapidfireai_integration.md

Install RapidFire AI, which includes Trackio as a dependency, using pip.

```bash
pip install rapidfireai
```

--------------------------------

### Complete wandb migration example

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/migration.md

Demonstrates a full migration from wandb to Trackio, showing that the rest of the code, including initialization, logging, and finishing, remains identical after changing the import statement.

```diff
- import wandb
+ import trackio as wandb
import numpy as np

wandb.init(
    project="image-classification",
    name="experiment-1",
    config={
        "learning_rate": 0.01,
        "batch_size": 32,
        "epochs": 10
    }
)

for epoch in range(10):
    loss = np.random.random()
    accuracy = np.random.random()
    
    wandb.log({
        "epoch": epoch,
        "loss": loss,
        "accuracy": accuracy,
        "learning_rate": wandb.config.learning_rate
    })

wandb.finish()
```

--------------------------------

### Write Access Token Example

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Example JSON payload for authenticating mutation tools on a local dashboard using a write token.

```json
{
  "project": "my-project",
  "run": "run-1",
  "write_token": "<token from startup output>"
}
```

--------------------------------

### Run Multiple Experiments

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

A comprehensive example demonstrating how to run multiple experiments in a loop, logging various metrics for each epoch.

```python
import random

num_experiments = 5
epochs = 100

for idx in range(num_experiments):
    experiment = trackio.init(
        project="quickstart", name=f"experiment_{idx}", space_id="quickstart-trackio"
    )

    for epoch in range(epochs):
        train_loss = random.uniform(0.2, 1.0)
        train_acc = random.uniform(0.6, 0.95)

        val_loss = train_loss - random.uniform(0.01, 0.1)
        val_acc = train_acc + random.uniform(0.01, 0.05)

        experiment.log(
            {
                "epoch": epoch,
                "train_loss": train_loss,
                "train_accuracy": train_acc,
                "val_loss": val_loss,
                "val_accuracy": val_acc,
            }
        )

    experiment.finish()
```

--------------------------------

### Set Go Environment Variables

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Set these environment variables before running the Go quickstart script. Ensure TRACKIO_SERVER_URL points to your deployed dashboard.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="go-quickstart"
export TRACKIO_RUN="go-run-1"
```

--------------------------------

### Launch Dashboard (Python)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/quickstart.md

Execute this Python command to start the trackio dashboard locally. The dashboard will provide access to your logged projects.

```python
import trackio

trackio.show()
```

--------------------------------

### Install Trackio for GPU/Apple Silicon Monitoring

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/track.md

Install Trackio with optional dependencies for system metrics monitoring. Use `[gpu]` for NVIDIA GPUs or `[apple-gpu]` for Apple Silicon Macs.

```bash
# NVIDIA GPU monitoring
pip install trackio[gpu]

# Apple Silicon system monitoring
pip install trackio[apple-gpu]
```

--------------------------------

### Initialize a Trackio Project

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/track.md

Initialize a new Trackio project. If the project already exists, it will be loaded. A new run is started automatically.

```python
import trackio

trackio.init(project="my_project")
```

--------------------------------

### init

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api.md

Initializes the Trackio environment. This is typically called once at the start of your script.

```APIDOC
## init

### Description
Initializes the Trackio environment.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Example JSON Output for Snapshot

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Example of the JSON output format when retrieving a metrics snapshot.

```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}
    ]
  }
}
```

--------------------------------

### Launch Dashboard for Specific Project

Source: https://github.com/gradio-app/trackio/blob/main/CLAUDE.md

Start the Trackio dashboard for a particular project by specifying its name.

```bash
trackio show --project "project_name"
```

--------------------------------

### Launch Trackio Dashboard from Python

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Start the Trackio dashboard programmatically. Optionally specify a project name or a custom frontend directory.

```python
import trackio

trackio.show()
```

```python
import trackio 

trackio.show(project="my-project")
```

```python
import trackio

trackio.show(frontend_dir="./my-trackio-frontend")
```

--------------------------------

### Run

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api.md

Starts a new experiment run. This should be called at the beginning of your experiment.

```APIDOC
## Run

### Description
Starts a new experiment run.

### Method
N/A (Function call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Get Project Summary

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve a summary of a specific project.

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

--------------------------------

### Launch Local Dashboard

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/launch.md

Run this command to launch the default Trackio dashboard locally. Ensure Trackio is installed and configured.

```sh
trackio show
```

```python
import trackio

trackio.show()
```

--------------------------------

### Launch Trackio Dashboard from Terminal

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Start the Trackio dashboard in your terminal. Optionally specify a project name to load.

```bash
trackio show
```

```bash
trackio show --project "my-project"
```

```bash
trackio show --frontend ./my-trackio-frontend
```

--------------------------------

### Import Trackio

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

Import the Trackio library to start using its functionalities.

```python
import trackio
```

--------------------------------

### Log Training Metrics with Trackio

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Initialize Trackio, log fake training and validation metrics over several epochs and runs, and then finish the logging session. This example demonstrates basic usage for tracking experiments.

```python
import trackio
import random
import time

runs = 3
epochs = 8


for run in range(runs):
    trackio.init(
        project="my-project",
        config={"epochs": epochs, "learning_rate": 0.001, "batch_size": 64}
    )

    for epoch in range(epochs):
        train_loss = random.uniform(0.2, 1.0)
        train_acc = random.uniform(0.6, 0.95)

        val_loss = train_loss - random.uniform(0.01, 0.1)
        val_acc = train_acc + random.uniform(0.01, 0.05)

        trackio.log({
            "epoch": epoch,
            "train_loss": train_loss,
            "train_accuracy": train_acc,
            "val_loss": val_loss,
            "val_accuracy": val_acc
        })

        time.sleep(0.2)

trackio.finish()
```

--------------------------------

### RAG Optimization Example with Trackio

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/rapidfireai_integration.md

Run a RAG pipeline optimization experiment with Trackio tracking enabled. Ensure Trackio is enabled via environment variables before initializing the Experiment.

```python
import os
os.environ["RF_TRACKIO_ENABLED"] = "true"

from rapidfireai import Experiment
from rapidfireai.evals.automl import List, RFGridSearch, RFLangChainRagSpec, RFvLLMModelConfig

experiment = Experiment(experiment_name="my-rag-experiment", mode="evals")

rag_spec = RFLangChainRagSpec(
    document_loader=your_document_loader,
    text_splitter=your_text_splitter,
    embedding_cls=your_embedding_class,
    search_kwargs={"k": List([5, 10])},  # 2 retrieval configs to compare
)

config_group = RFGridSearch({
    "vllm_config": RFvLLMModelConfig(rag=rag_spec, ...),
    "batch_size": 32,
    ...
})

experiment.run_evals(
    config_group=config_group,
    dataset=eval_dataset,
    num_actors=1,
    num_shards=4,
)
```

--------------------------------

### Launch Training Script via CLI

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/ml_agents.md

Launches the Python training script from the command line. This is a standard way for agents to start a training process that utilizes Trackio for monitoring.

```bash
python train.py
```

--------------------------------

### Set JavaScript Environment Variables

Source: https://github.com/gradio-app/trackio/blob/main/contrib/README.md

Set these environment variables before running the JavaScript quickstart script. Ensure TRACKIO_SERVER_URL points to your deployed dashboard.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="js-quickstart"
export TRACKIO_RUN="js-run-1"
```

--------------------------------

### Get Run Summary (CLI)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve a detailed summary of a specific run within a project, including metrics and configuration. Use the --json flag for JSON output.

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

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

--------------------------------

### Query Project Data with SQL

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Use the trackio CLI to perform read-only SQL queries on project data when standard list and get commands are insufficient. Replace `<name>` with your project name.

```bash
trackio query project --project <name> --sql "SELECT ..."
```

--------------------------------

### Get Project Summary (CLI)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve a summary of a project, including run counts and recent activity. Use the --json flag for machine-readable output.

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

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

--------------------------------

### HTTP API: Get Alerts

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/alerts.md

Query alerts via the `/get_alerts` endpoint if the Trackio dashboard is running. This example uses `gradio_client` to interact with the API.

```python
from gradio_client import Client

client = Client("http://127.0.0.1:7860/")
alerts = client.predict(
    project="my-project",
    run=None,
    level="error",
    since="2025-06-01T00:00:00",
    api_name="/get_alerts",
)
```

--------------------------------

### Automation Script: Get Latest Loss Value

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Example of using Trackio CLI in a bash script to fetch the latest metric value and process it with `jq`.

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

--------------------------------

### Bash API Usage Examples

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Interact with the Trackio MCP server using curl. Make POST requests to the `/api/{tool_name}` endpoints with JSON payloads.

```bash
# Get all projects
curl -s -X POST http://127.0.0.1:7860/api/get_all_projects \
  -H "Content-Type: application/json" -d '{}'

# Get runs for a project
curl -s -X POST http://127.0.0.1:7860/api/get_runs_for_project \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project"}'

# Get values for a metric
curl -s -X POST http://127.0.0.1:7860/api/get_metric_values \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project", "run": "run-1", "metric_name": "loss"}'
```

--------------------------------

### Initialize Experiment with Configuration

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

Initialize an experiment and attach a configuration dictionary to it. The configuration can be accessed via the `config` attribute.

```python
config = {
    "lr": 0.01,
}
experiment_2 = trackio.init(
    project="quickstart",
    name="experiment_2",
    space_id="quickstart-trackio",
    config=config,
)
```

--------------------------------

### Generic Webhook Payload Example

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/alerts.md

Example of the JSON payload sent to generic webhooks.

```json
{
    "level": "warn",
    "title": "Validation loss spike",
    "text": "val_loss=2.34 exceeded threshold 2.0",
    "project": "my-project",
    "run": "brave-sunset-0",
    "step": 42,
    "timestamp": "2025-06-15T14:30:00+00:00"
}
```

--------------------------------

### List All Projects

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

List all available projects locally. Use the `--json` flag to output the results in JSON format.

```sh
trackio list projects
```

```sh
trackio list projects --json
```

--------------------------------

### Set Up Trackio Go Client Environment Variables

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-go/README.md

Set the necessary environment variables before running the Go client. TRACKIO_SERVER_URL points to your Trackio dashboard, HF_TOKEN provides authentication, and TRACKIO_PROJECT and TRACKIO_RUN specify the experiment details.

```bash
export TRACKIO_SERVER_URL="https://your-space-url.hf.space"
export HF_TOKEN="hf_…"
export TRACKIO_PROJECT="go-quickstart"
export TRACKIO_RUN="go-run-1"

go run ./examples/quickstart
```

--------------------------------

### Log Metrics with Trackio Go Client

Source: https://github.com/gradio-app/trackio/blob/main/contrib/trackio-go/README.md

Initialize the client and log metrics. Ensure environment variables TRACKIO_SERVER_URL, HF_TOKEN, TRACKIO_PROJECT, and TRACKIO_RUN are set before running.

```go
c := trackio.New(
  trackio.WithBaseURL("https://your-space-url.hf.space"),
  trackio.WithProject("my-project"),
  trackio.WithRun("my-run"),
)

c.Log(map[string]float64{"loss": 0.5, "acc": 0.8}, 0, "")
c.Log(map[string]float64{"loss": 0.4, "acc": 0.82}, 1, "")
c.Flush(context.Background())
```

--------------------------------

### Finish Experiment with Configuration

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

Finish an experiment that was initialized with a configuration.

```python
experiment_2.finish()
```

--------------------------------

### Install Trackio with MCP dependency

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Install the trackio package with the optional MCP dependency using pip.

```bash
pip install "trackio[mcp]"
```

--------------------------------

### Initialize Trackio and Log Metrics in Training Script

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/ml_agents.md

Initializes Trackio for a project and run, logging key training metrics like loss and accuracy. Use this at the beginning of your training loop. Ensure all necessary parameters for `trackio.init` and `trackio.log` are correctly set.

```python
import trackio
import torch

trackio.init(
    project="cifar10-hparam-search",
    name="run-lr0.001-bs64",
    config={
        "learning_rate": 0.001,
        "batch_size": 64,
        "optimizer": "adamw",
        "epochs": 50,
        "weight_decay": 1e-4,
    },
)

model = build_model()
optimizer = torch.optim.AdamW(
    model.parameters(), lr=0.001, weight_decay=1e-4
)

best_val_loss = float("inf")
patience_counter = 0
patience_limit = 5

for epoch in range(50):
    train_loss = train_one_epoch(model, train_loader, optimizer)
    val_loss, val_acc = evaluate(model, val_loader)

    trackio.log({
        "train_loss": train_loss,
        "val_loss": val_loss,
        "val_accuracy": val_acc,
        "learning_rate": optimizer.param_groups[0]["lr"],
    })
```

--------------------------------

### Initialize Trackio and Log Alerts

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Initializes Trackio with project details and webhook configuration, then logs metrics and triggers alerts based on training conditions. Ensure webhook_min_level is set appropriately for desired alert notifications.

```python
import trackio

trackio.init(
    project="my-project",
    webhook_url="https://hooks.slack.com/services/T.../B.../xxx",
    webhook_min_level=trackio.AlertLevel.WARN,
)

for epoch in range(100):
    loss = train(...)
    trackio.log({"loss": loss})

    if epoch > 10 and loss > 5.0:
        trackio.alert(
            title="Loss spike",
            text=f"Loss jumped to {loss:.2f} at epoch {epoch}",
            level=trackio.AlertLevel.ERROR,
        )

trackio.finish()
```

--------------------------------

### Initialize Trackio with Hugging Face Space ID

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/deploy_embed.md

Pass a `space_id` to `init` to use an existing or automatically deploy a new Hugging Face Space. Ensure you are logged in with `huggingface-cli` and have write permissions.

```python
trackio.init(project="my-project", space_id="orgname/space_id")
```

```python
trackio.init(project="my-project", space_id="username/space_id")
```

--------------------------------

### Initialize Trackio API

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/python_api.md

Instantiates the main entry point for the Trackio Python API.

```python
api = trackio.Api()
```

--------------------------------

### Launch Dashboard with Project (Python)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/quickstart.md

Use this Python command to launch the dashboard and load a specific project by name.

```python
import trackio 

trackio.show(project="my-project")
```

--------------------------------

### Get Run Summary

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve a summary of a specific run within a project.

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

--------------------------------

### Get Runs for a Project

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/python_api.md

Retrieve a collection of runs associated with a specific project.

```APIDOC
## Get Runs for a Project

### Description
Returns a collection of runs for the specified project. Raises `ValueError` if the project doesn't exist.

### Method
```python
api.runs(project: str) -> Runs
```

### Parameters
#### Path Parameters
- **project** (str) - Required - The name of the project to retrieve runs from.
```

--------------------------------

### Sync Local Project to Hugging Face Space

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Upload a local project to a Hugging Face Space using the `sync` command. You can specify the project and Space ID. The `--sdk static` option deploys as a read-only, bucket-backed Space.

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

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

--------------------------------

### Update Local Repository

Source: https://github.com/gradio-app/trackio/blob/main/RELEASE.md

Ensure your local repository is up to date with the upstream main branch before starting a release.

```bash
git checkout main
git pull origin main
```

--------------------------------

### Query Command

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

A general-purpose read-only SQL query command for data not covered by specific 'list' or 'get' commands.

```APIDOC
## Query Command

Use `trackio query` when you need a catch-all read-only SQL query that is not already covered by `trackio list` or `trackio get`.
```

--------------------------------

### Get Metric Values

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves all values for a specific metric within a run. Supports filtering by step or time.

```APIDOC
## Get Metric Values

Get all values for a specific metric in a run:

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

Output in JSON format:

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

The output includes:
- Step number
- Timestamp
- Metric value

#### Filtering by Step or Time

You can filter metric values to a specific step or a window around a step/timestamp. This is useful for inspecting metrics around the time an alert was fired.

```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 | Description |
|------|-------------|
| `--step N` | Return the metric at exactly step N |
| `--around N` | Return metrics in a window around step N |
| `--at-time T` | Return metrics in a window around ISO 8601 timestamp T |
| `--window W` | Window size: ±steps for `--around`, ±seconds for `--at-time` (default: 10) |
```

--------------------------------

### Bash API Usage

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Example of how to interact with the Trackio API using curl commands to retrieve project, run, and metric data.

```APIDOC
## Bash API Usage

This example demonstrates how to use `curl` commands in Bash to interact with the Trackio API.

### Description

Interact with Trackio's API endpoints to retrieve project lists, runs associated with a project, and specific metric values.

### Code Examples

#### Get all projects

```bash
curl -s -X POST http://127.0.0.1:7860/api/get_all_projects \
  -H "Content-Type: application/json" -d '{}'
```

#### Get runs for a project

```bash
curl -s -X POST http://127.0.0.1:7860/api/get_runs_for_project \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project"}'
```

#### Get values for a metric

```bash
curl -s -X POST http://127.0.0.1:7860/api/get_metric_values \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project", "run": "run-1", "metric_name": "loss"}'
```
```

--------------------------------

### Initialize an Experiment

Source: https://github.com/gradio-app/trackio/blob/main/examples/notebooks/quickstart.ipynb

Initialize a new experiment within a project. Ensure your Hugging Face token is accessible as HF_TOKEN.

```python
experiment_1 = trackio.init(
    project="quickstart", name="experiment_1", space_id="quickstart-trackio"
)
```

--------------------------------

### Get Specific Metric Values

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve the values for a specific metric within a run. This command can also query remote Spaces.

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

```sh
trackio get metric --project "my-project" --run "my-run" --metric "loss" --space username/my-space --json
```

--------------------------------

### Get Report Content

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves markdown report entries for a specific report name within a run. Can output in JSON format.

```APIDOC
## Get Report Content

Print markdown report entries for a specific report name in a run:

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

Output in JSON format:

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

--------------------------------

### Initialize Trackio with Self-hosted Server URL

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Use `server_url` in `trackio.init()` to point training jobs to your own Trackio server. A `write_token` can be included in the URL or set via the `TRACKIO_WRITE_TOKEN` environment variable.

```python
trackio.init(project="my-project", server_url="http://127.0.0.1:7860?write_token=YOUR_TOKEN")
```

--------------------------------

### Initialize a Trackio Project with a Run Name

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/track.md

Initialize a Trackio project and assign a meaningful name to the current run for easier organization.

```python
trackio.init(project="my_project", name="my_first_run")
```

--------------------------------

### Get Project Summary

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves a detailed summary of a project, including the number of runs and recent activity. Can output in JSON format.

```APIDOC
## Get Project Summary

Get a detailed summary of a project, including the number of runs and recent activity:

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

Output in JSON format:

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

The summary includes:
- Project name
- Number of runs
- List of all runs
- Last activity (maximum step across all runs)
```

--------------------------------

### List Projects

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

List all available projects. Add the `--space` flag to list projects on a remote Space.

```sh
trackio list projects
```

```sh
trackio list projects --space username/my-space
```

--------------------------------

### Get Metrics Snapshot

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves all metrics at or around a specific step or timestamp in a single call, providing a snapshot of the run's state.

```APIDOC
## Get Metrics Snapshot

Get **all** metrics at/around a step or timestamp in a single call. This is the fastest way for an agent to understand the state of a run at a specific point — for example, right when an alert fired.

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

Example JSON output:

```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}
    ]
  }
}
```
```

--------------------------------

### Get Run Summary

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves a detailed summary of a specific run within a project, including metrics and configuration. Can output in JSON format.

```APIDOC
## Get Run Summary

Get a detailed summary of a specific run, including metrics and configuration:

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

Output in JSON format:

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

The summary includes:
- Project and run names
- Number of log entries
- Last step
- List of all metrics
- Run configuration (excluding internal fields)
```

--------------------------------

### CLI: List All Alerts

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/alerts.md

Retrieve all alerts for a given project using the `trackio get alerts` command. You can filter by run, level, or timestamp.

```bash
# List all alerts for a project
trackio get alerts --project "my-project"
```

```bash
# Filter by run
trackio get alerts --project "my-project" --run "brave-sunset-0"
```

```bash
# Filter by level
trackio get alerts --project "my-project" --level error
```

```bash
# Only alerts after a specific timestamp (useful for polling)
trackio get alerts --project "my-project" --since "2025-06-01T00:00:00"
```

```bash
# JSON output for programmatic consumption
trackio get alerts --project "my-project" --json
```

--------------------------------

### JavaScript API Usage

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Example of how to interact with the Trackio API using JavaScript's fetch API to retrieve project, run, and metric data.

```APIDOC
## JavaScript API Usage

This example demonstrates how to use the `fetch` API in JavaScript to interact with the Trackio API.

### Description

Interact with Trackio's API endpoints to retrieve project lists, runs associated with a project, and specific metric values.

### Code Example

```javascript
const base = "http://127.0.0.1:7860";

async function call(name, payload = {}) {
  const res = await fetch(`${base}/api/${name}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  return (await res.json()).data;
}

console.log("Projects:", await call("get_all_projects"));
console.log("Runs:", await call("get_runs_for_project", { project: "my-project" }));
console.log("Loss:", await call("get_metric_values", {
  project: "my-project",
  run: "run-1",
  metric_name: "loss",
}));
```
```

--------------------------------

### Initialize Trackio with Hugging Face Space ID

Source: https://github.com/gradio-app/trackio/blob/main/README.md

Pass a `space_id` to `trackio.init()` to use an existing or deploy a new Hugging Face Space. Ensure you are logged in with `huggingface-cli` and have write permissions.

```python
trackio.init(project="my-project", space_id="orgname/space_id")
```

```python
trackio.init(project="my-project", space_id="username/space_id")
```

--------------------------------

### Initialize Trackio with Environment Variable

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/alerts.md

Initialize Trackio without a webhook_url, automatically picking it up from an environment variable.

```python
trackio.init(project="my-project")
```

--------------------------------

### Python API Usage

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Example of how to interact with the Trackio API using Python's httpx library to fetch project, run, and metric data.

```APIDOC
## Python API Usage

This example demonstrates how to use the `httpx` library in Python to interact with the Trackio API.

### Description

Interact with Trackio's API endpoints to retrieve project lists, runs associated with a project, and specific metric values.

### Code Example

```python
import httpx

base = "http://127.0.0.1:7860"

projects = httpx.post(f"{base}/api/get_all_projects").json()["data"]
print("Projects:", projects)

runs = httpx.post(
    f"{base}/api/get_runs_for_project",
    json={"project": "my-project"},
).json()["data"]
print("Runs:", runs)

values = httpx.post(
    f"{base}/api/get_metric_values",
    json={"project": "my-project", "run": "run-1", "metric_name": "loss"},
).json()["data"]
print("Loss values:", values)
```
```

--------------------------------

### Get Snapshot of Metrics at a Specific Step

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieve all metric values at a particular step for a given run. Use `--json` for structured output.

```sh
trackio get snapshot --project "my-project" --run "my-run" --step 200 --json
```

--------------------------------

### Sync Local Project to Hugging Face Space (Shell)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/quickstart.md

Sync your local trackio project data to a Hugging Face Space using this shell command. The Space will be created if it doesn't exist.

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

--------------------------------

### List All Runs Across Projects

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/python_api.md

Iterates through all projects and lists the names of runs within each project. Requires importing `SQLiteStorage` to get project names.

```python
import trackio
from trackio.sqlite_storage import SQLiteStorage

api = trackio.Api()

# Get all projects
projects = SQLiteStorage.get_projects()

# List runs in each project
for project in projects:
    print(f"\nProject: {project}")
    runs = api.runs(project)
    for run in runs:
        print(f"  - {run.name}")
```

--------------------------------

### Launch Trackio Dashboard via CLI

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/rapidfireai_integration.md

Use this command to launch the Trackio dashboard from your terminal. Replace 'my-sft-experiment' with your specific project name.

```bash
trackio show --project "my-sft-experiment"
```

--------------------------------

### Integration: Pipe Output to jq for Filtering

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Demonstrates piping the JSON output of `trackio list runs` to `jq` for filtering runs that start with 'train'.

```sh
trackio list runs --project "my-project" --json | jq '.runs[] | select(startswith("train"))'
```

--------------------------------

### Use Custom Frontend

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/launch.md

Replace the default Trackio dashboard with your own static frontend. Trackio will serve your custom frontend and live-reload it as files change.

```sh
trackio show --frontend ./my-trackio-frontend
```

```python
import trackio 
trackio.show(frontend_dir="./my-trackio-frontend")
```

--------------------------------

### Get System Metric Values

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Retrieves system metric values for a run. If no metric name is provided, all system metrics are returned. Can output in JSON format.

```APIDOC
## Get System Metric Values

Get system metric values for a run. If no metric name is provided, all system metrics are returned:

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

Output in JSON format:

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

--------------------------------

### Enable MCP Server via Environment Variable

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/api_mcp_server.md

Enable the MCP server by setting the `GRADIO_MCP_SERVER` environment variable to `True` before running the `trackio show` command.

```bash
export GRADIO_MCP_SERVER=True
trackio show
```

--------------------------------

### Sync Local Project to Hugging Face Space (Python)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/quickstart.md

Use this Python command to synchronize your local trackio project with a specified Hugging Face Space. This command will create the Space if it is not found.

```python
trackio.sync(project="my-project", space_id="username/space_id")
```

--------------------------------

### Get Report Content (CLI)

Source: https://github.com/gradio-app/trackio/blob/main/docs/source/cli_commands.md

Print markdown report entries for a specific report name in a run. Use the --json flag for JSON output.

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

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