History

Jeremie Fraeys 04ac745b01 refactor(cli): Rename note to annotate and re-add experiment command - Renamed note.zig to annotate.zig (preserves user's preferred naming) - Updated all references from 'ml note' to 'ml annotate' - Re-added experiment.zig with create/list/show subcommands - Updated main.zig dispatch: 'a' for annotate, 'e' for experiment - Updated printUsage and test block to reflect changes		2026-02-20 21:32:01 -05:00
..
scripts	feat(cli): embed SQLite and unify commands for local mode	2026-02-20 15:50:04 -05:00
src	refactor(cli): Rename note to annotate and re-add experiment command	2026-02-20 21:32:01 -05:00
tests	refactor(cli): reorganize queue commands and add logs test	2026-02-18 12:45:54 -05:00
build.zig	refactor(cli): update build system and config for local mode	2026-02-20 15:50:52 -05:00
Makefile	refactor(cli): update build system and config for local mode	2026-02-20 15:50:52 -05:00
README.md	refactor(cli): update build system and config for local mode	2026-02-20 15:50:52 -05:00
src.zig	feat(cli): enhance Zig CLI with new commands and improved networking	2026-02-12 12:05:10 -05:00

README.md

ML CLI

Fast CLI tool for managing ML experiments. Supports both local mode (SQLite) and server mode (WebSocket).

Quick Start

# 1. Build
zig build

# 2. Initialize local tracking (creates fetch_ml.db)
./zig-out/bin/ml init

# 3. Create experiment and run locally
./zig-out/bin/ml experiment create --name "baseline"
./zig-out/bin/ml run start --experiment <id> --name "run-1"
./zig-out/bin/ml experiment log --run <id> --name loss --value 0.5
./zig-out/bin/ml run finish --run <id>

Commands

Local Mode Commands (SQLite)

ml init - Initialize local experiment tracking database
ml experiment create --name <name> - Create experiment locally
ml experiment list - List experiments from SQLite
ml experiment log --run <id> --name <key> --value <val> - Log metrics
ml run start --experiment <id> [--name <name>] - Start a run
ml run finish --run <id> - Mark run as finished
ml run fail --run <id> - Mark run as failed
ml run list - List all runs

Server Mode Commands (WebSocket)

ml sync <path> - Sync project to server
ml queue <job1> [job2 ...] [--commit <id>] [--priority N] [--note <text>] - Queue jobs
ml status - Check system/queue status
ml validate <commit_id> [--json] [--task <task_id>] - Validate provenance
ml cancel <job> - Cancel a running/queued job

Shared Commands (Auto-detect Mode)

ml experiment log|show|list|delete - Works in both local and server mode
ml monitor - Launch TUI (local SQLite or remote SSH)

Notes:

Commands auto-detect mode from config (sqlite:// vs wss://)
--json mode is designed to be pipe-friendly

Configuration

Local Mode (SQLite)

# .fetchml/config.toml or ~/.ml/config.toml
tracking_uri = "sqlite://./fetch_ml.db"
artifact_path = "./experiments/"
sync_uri = ""  # Optional: server to sync with

Server Mode (WebSocket)

# ~/.ml/config.toml
worker_host = "worker.local"
worker_user = "mluser"
worker_base = "/data/ml-experiments"
worker_port = 22
api_key = "your-api-key"

Building

Development

cd cli
zig build

Production (requires SQLite in assets/)

cd cli
make build-sqlite    # Fetch SQLite amalgamation
zig build prod       # Build with embedded SQLite

Install

# Install to system
make install

# Or copy binary manually
cp zig-out/bin/ml /usr/local/bin/

Need Help?

ml --help - Show command help
ml <command> --help - Show command-specific help