fetch_ml/cli

ML CLI

Fast CLI tool for managing ML experiments.

Quick Start

# 1. Build
zig build

# 2. Setup configuration
./zig-out/bin/ml init

# 3. Run experiment
./zig-out/bin/ml sync ./my-experiment --queue

Commands

• ml init - Setup configuration
• ml sync <path> - Sync project to server
• ml queue <job1> [job2 ...] [--commit <id>] [--priority N] [--note <text>] - Queue one or more jobs
• ml status - Check system/queue status for your API key
• ml validate <commit_id> [--json] [--task <task_id>] - Validate provenance + integrity for a commit or task (includes run_manifest.json consistency checks when validating by task)
• ml info <path|id> [--json] [--base <path>] - Show run info from run_manifest.json (by path or by scanning finished/failed/running/pending)
• ml annotate <path|run_id|task_id> --note <text> [--author <name>] [--base <path>] [--json] - Append a human annotation to run_manifest.json
• ml narrative set <path|run_id|task_id> [--hypothesis <text>] [--context <text>] [--intent <text>] [--expected-outcome <text>] [--parent-run <id>] [--experiment-group <text>] [--tags <csv>] [--base <path>] [--json] - Patch the narrative field in run_manifest.json
• ml monitor - Launch monitoring interface (TUI)
• ml cancel <job> - Cancel a running/queued job you own
• ml prune --keep N - Keep N recent experiments
• ml watch <path> - Auto-sync directory
• ml experiment log|show|list|delete - Manage experiments and metrics

Notes:

• --json mode is designed to be pipe-friendly: machine-readable JSON is emitted to stdout, while user-facing messages/errors go to stderr.
• When running ml validate --task <task_id>, the server will try to locate the job's run_manifest.json under the configured base path (pending/running/finished/failed) and cross-check key fields (task id, commit id, deps, snapshot).
• For tasks in running, completed, or failed state, a missing run_manifest.json is treated as a validation failure. For queued tasks, it is treated as a warning (the job may not have started yet).

Experiment workflow (minimal)

• ml sync ./my-experiment --queue
  Syncs files, computes a unique commit ID for the directory, and queues a job.

• ml queue my-job
  Queues a job named my-job. If --commit is omitted, the CLI generates a random commit ID and records (job_name, commit_id) in ~/.ml/history.log so you don't have to remember hashes.

• ml queue my-job --note "baseline run; lr=1e-3" Adds a human-readable note to the run; it will be persisted into the run's run_manifest.json (under metadata.note).

• ml experiment list
  Shows recent experiments from history with alias (job name) and commit ID.

• ml experiment delete <alias|commit>
  Cancels a running/queued experiment by job name, full commit ID, or short commit prefix.

Configuration

Create ~/.ml/config.toml:

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

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