# ML CLI

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

## Quick Start

```bash
# 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)

```toml
# .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)

```toml
# ~/.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

```bash
cd cli
zig build
```

### Production (requires SQLite in assets/)

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

## Install

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