CLI reference

macbatch [--verbose] <command> [options]

--verbose / -v raises logging to DEBUG. Logs are JSON lines on stderr and appended to ~/.macbatch/logs/macbatch.jsonl.

setup

Bootstrap this Mac as a worker: install Ollama, pull a model, write config, ping the control plane.

macbatch setup --control-url https://your-control-plane

Option	Default	Meaning
--control-url	http://127.0.0.1:8000	Control plane to join
--jobs	embed	Comma-separated job types this worker accepts
--model	nomic-embed-text	Model to pull
--worker-id	generated	Override the worker identity
--skip-ollama	off	Skip runtime install and model pull entirely
--no-install	off	Do not brew install ollama; fail if it is missing

Exits non-zero if the Ollama bootstrap fails. A control plane that is unreachable produces a warning, not a failure.

control

macbatch control start [--host 127.0.0.1] [--port 8000] [--tunnel] [--public]
macbatch control url
macbatch control workers

Action	Does
start	Runs the control plane on this machine
url	Prints the local URL, the public tunnel URL, and what workers will use
workers	Table of registered workers with alive state and counters

Option	Meaning
--tunnel	Start a Cloudflare quick tunnel and print a public URL. Needs cloudflared.
--public	Bind 0.0.0.0 for LAN access. Prefer --tunnel for other networks.
--port	Change the port. Use this rather than killing a healthy server.

If the port already holds a healthy macbatch control plane, start reports it and exits 0; --tunnel attaches to it instead of starting a second server.

serve

Run the worker loop.

macbatch serve [--control-url URL] [--worker-id ID] [--once]
               [--lease-limit N] [--max-concurrent N]

Option	Default	Meaning
--control-url	from config	Override and persist the control plane URL
--worker-id	from config	Override the worker identity
--once	off	Process one lease batch, then exit. Useful in scripts and CI.
--lease-limit	2	Shards leased per round trip
--max-concurrent	2	Shards processed in parallel

Writes its pid to ~/.macbatch/state/serve.pid so macbatch sleep can stop it. Any option given here is merged into the saved config.

sleep

macbatch sleep

Sends SIGTERM to the recorded pid, clears the temp cache, and posts an offline heartbeat. Model weights are kept. If serve is in the foreground, Ctrl+C is equivalent.

clean

macbatch clean [--yes|-y]

Clears ~/.macbatch/cache/. Prompts unless -y. Never touches Ollama models — use ollama rm <model>.

status

Prints the config path, worker id, effective control URL, public URL, job types, models, and whether serve is running, then queries the control plane for the worker list.

doctor

Preflight checks: ollama, brew, cloudflared, config file, control-plane /health, and the Ollama API. Each line is OK or FAIL with detail.

bench

macbatch bench embed --n 500 --mode solo --shard-size 32

Option	Default	Meaning
--n	500	Item count
--mode	solo	Comparison label only — does not change behaviour
--model	nomic-embed-text	Model
--shard-size	32	Items per task
--corpus	—	JSONL path; synthetic corpus generated if omitted
--control-url	from config	Override the control plane

embed is the only supported workload. Fails immediately if no worker is alive. See Methodology.

corpus

macbatch corpus --n 500 [--out path.jsonl]

Writes a synthetic JSONL corpus. Defaults to data/embed_<n>.jsonl in a source checkout, or ~/.macbatch/data/ when installed.

version

macbatch version