refactor(cli): Update build system and core infrastructure

- Makefile: Update build targets for native library integration
- build.zig: Add SQLite linking and native hash library support
- scripts/build_rsync.sh: Update rsync embedded binary build process
- scripts/build_sqlite.sh: Add SQLite constants generation script
- src/assets/README.md: Document embedded asset structure
- src/utils/rsync_embedded_binary.zig: Update for new build layout

2026-02-20 21:39:51 -05:00

2.6 KiB

Raw Blame History

title	url	weight
Zig CLI Guide	/zig-cli/	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:

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

# 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:

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:

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.

2.6 KiB Raw Blame History Unescape Escape