---
title: "Zig CLI Guide"
url: "/zig-cli/"
weight: 3
---

# Zig CLI Guide

Lightweight command-line interface (`ml`) for managing ML experiments. Built in Zig for minimal size and fast startup.

## Architecture

The CLI follows a modular 3-layer architecture:

```
src/
├── core/                    # Shared foundation
│   ├── context.zig         # Execution context (allocator, config, mode dispatch)
│   ├── output.zig          # Unified JSON/text output helpers
│   └── flags.zig           # Common flag parsing
├── local/                   # Local mode operations (SQLite)
│   └── experiment_ops.zig  # Experiment CRUD for local DB
├── server/                  # Server mode operations (WebSocket)
│   └── experiment_api.zig  # Experiment API for remote server
└── commands/                # Thin command routers
    ├── experiment.zig      # ~100 lines (was 887)
    └── queue.zig           # Modular with queue/ submodules
```

### Mode Dispatch

Commands use `core.context.Context` to auto-detect local vs server mode:

```zig
var ctx = core.context.Context.init(allocator, cfg, flags.json);
if (ctx.isLocal()) {
    return try local.experiment.list(ctx.allocator, ctx.json_output);
} else {
    return try server.experiment.list(ctx.allocator, ctx.json_output);
}
```

## Quick start

```bash
# Build locally
cd cli && make all

# Or download a release binary
curl -LO https://github.com/jfraeys/fetch_ml/releases/latest/download/ml-<platform>.tar.gz
tar -xzf ml-<platform>.tar.gz && chmod +x ml-<platform>
```

## Configuration

The CLI reads `~/.ml/config.toml` and respects `FETCH_ML_CLI_*` env vars:

```toml
worker_host = "127.0.0.1"
worker_user = "dev_user"
worker_base = "/tmp/ml-experiments"
worker_port = 22
api_key = "your-api-key"
```

Example overrides:

```bash
export FETCH_ML_CLI_HOST="myserver"
export FETCH_ML_CLI_API_KEY="prod-key"
```

## Core commands

- `ml status` – system status
- `ml queue <job>` – queue a job
- `ml cancel <job>` – cancel a job
- `ml dataset list` – list datasets
- `ml monitor` – launch TUI over SSH (remote UI)

`ml status --json` may include an optional `prewarm` field when the worker is prefetching datasets for the next queued task.

## Build flavors

- `make all` – release‑small (default)
- `make tiny` – extra‑small binary
- `make fast` – release‑fast

All use `zig build-exe` with `-OReleaseSmall -fstrip` and are compatible with Linux/macOS/Windows.

## CI/CD

The release workflow builds cross‑platform binaries and packages them with checksums. See `.forgejo/workflows/release-mirror.yml`.