`zyme` CLI reference

The zyme command drives the optimization loop behind Building a patch. Install it via Environment setup, then run zyme --help to see the live command map.

Commands are grouped by lifecycle role. High-traffic commands include EXAMPLES sections — run zyme <cmd> --help for the full set.

Core loop — edit / measure / decide

Command	Purpose
`zyme init`	Scaffold a new task in cwd
`zyme run`	Commit pipeline edit, measure, append `pending` row to results.tsv
`zyme dryrun`	Run pipeline + evaluate without committing or logging
`zyme accept`	Promote latest pending row to `keep`; advance best
`zyme reject`	Mark latest pending row as `discard`; auto-restore pipeline
`zyme rollback`	Demote the most recent accepted round; re-point best to the prior keep

Measurement — references and verification

Command	Purpose
`zyme baseline record`	Manually enter a baseline measurement
`zyme baseline reference --tier <T>`	Run reference.py/.R once per tier, populate `reference_output_<T>/`
`zyme baseline noise`	Calibrate intrinsic-noise estimates (stochastic algorithms)
`zyme baseline promote`	Promote a rerun row as the new baseline
`zyme baseline rebench --threads 1,4,8`	Re-time baseline at multiple thread counts
`zyme baseline list`	List recorded baselines
`zyme baseline show`	Show a specific baseline row
`zyme profile`	Profile one pipeline run; writes hotspot evidence under `profile_history/`
`zyme verify`	Full (tier × threading) cube; writes `verify.tsv` with PASS/SOFT/HARD verdicts
`zyme attest`	Packaging ship gate: full tier sweep (default `--reps 2`); commits `package_verify.tsv`

Analysis — read-only dashboards

Command	Purpose
`zyme status`	Round count, best speedup, current pipeline state
`zyme plot`	Render speed-vs-round plot from results.tsv
`zyme scan`	Workspace-wide dashboard across multiple tasks
`zyme registry`	Searchable registry of optimized functions + hot dependency engines (`rebuild` / `query` / `suggest` / `list`)
`zyme audit`	Replay the audit log for the current task

Workflow — multi-task / templates

Command	Purpose
`zyme dispatch run`	Run multiple tasks in parallel under a single dispatcher
`zyme dispatch status`	Status of all dispatched tasks
`zyme dispatch logs`	Stream logs from dispatched tasks
`zyme dispatch stop`	Stop a running dispatcher
`zyme bench register-template`	Register a benchmark template
`zyme bench list-templates`	List available templates
`zyme bench init`	Instantiate a template into a new task
`zyme bench list`	List benchmark suites
`zyme prompt save`	Save the current task’s prompt set into the registry
`zyme prompt list`	List registered prompts
`zyme prompt show`	Print a registered prompt
`zyme prompt diff`	Diff between two prompt versions
`zyme prompt use`	Activate a prompt version for the current task
`zyme prompt annotate`	Annotate a prompt with a note

Utility — one-shot tools

Command	Purpose
`zyme inspect-parallelism`	Probe upstream’s parallelism knobs (numba / openmp / Ray)
`zyme datasets`	Manage the workspace `/datasets/` layer (shared + per-task)
`zyme publish-speedups`	Manually publish a task’s speedups.tsv to the shipped package

High-traffic commands in detail

`zyme init`

zyme init <target_repo> [<target_function>] [--dataset <path>] [--field Bio|OtherField]
         [--no-clone] [--no-bench-snapshot] [--language python|R]

Scaffold a task in cwd. See Initialization for the full walkthrough.

Example

mkdir test_findallmarkers && cd test_findallmarkers
zyme init https://github.com/satijalab/seurat FindAllMarkers

`zyme run`

zyme run "<hypothesis>"
        [--task-dir <path>]              # defaults to cwd
        [--dataset <tier_or_name>]       # which dataset/tier to measure on
        [--extra-tiers <t1,t2,...>]      # also measure these (no separate decision)
        [--rerun --n <N>]                # re-time current HEAD without a new decision
        [--setup]                        # allow task-definition file changes (Initialization only)

Example

$EDITOR pipeline/run.py
zyme run "vectorize the inner cosine loop"          # decision round
zyme run --rerun --n 3                              # 3 reps, no decision

`zyme accept`

zyme accept -m "<note>" [--task-dir <path>]

Promote the latest pending row to keep. Advances best state. Updates memory/best_state.md.

`zyme reject`

zyme reject -m "<note>" [--task-dir <path>]

Mark latest pending row as discard. Automatically restores pipeline/run.py/.R to last accepted state.

`zyme dryrun`

zyme dryrun [--task-dir <path>] [--dataset <tier>]

Run pipeline + evaluate, print metrics, don’t commit, don’t log.

`zyme profile`

zyme profile [<label>]
             [--dataset <tier_or_name>]
             [--backend full|cpu|mem|native]
             [--json]
             [--no-archive]
             [--diff <A> --diff-against <B>]

Run the task pipeline once under a profiler. This is diagnostic only: it does not write results.tsv, does not commit, and does not run evaluate.py/.R.

Use it after initialization to find the first real bottleneck, and re-run it when several accepted rounds stop moving the dominant cost.

Common runs

zyme profile --dataset tiny                    # default backend=full
zyme profile "baseline tiny" --backend cpu     # cheap call counts
zyme profile --backend mem --dataset medium    # allocation pressure
zyme profile --json | jq .actionable_hotspots  # machine-readable

Backends

Backend	Python	R	Use when
`full`	Scalene, fallback to cProfile	profvis/Rprof, fallback to Rprof	Default. Good first profile: CPU, memory, native split where available
`cpu`	cProfile	Rprof	Cheap function-level timing and call counts
`mem`	memray	Rprof with memory profiling	You need allocation pressure, not just wall time
`native`	macOS `sample(1)`	macOS `sample(1)`	You need to see inside BLAS, Rcpp, Cython, or forked workers

Outputs

profile_history/<run-id>/profile.json
profile_history/<run-id>/run.log
profile_history/<run-id>/<raw-profiler-artifact>
profile_history/latest/profile.json

Read profile_history/latest/profile.json first. The most useful fields are layer_breakdown, per_layer_top, actionable_hotspots, and override_summary.

Compare two profiles

zyme profile --diff history:baseline \
             --diff-against current

current means the latest profile. history:<text> picks the most recent profile_history/ run whose directory name contains that text.

`zyme rollback`

zyme rollback [-m <reason>] [--dry-run]

Demote the most recent accepted (keep) commit and re-point best.ref to the prior keep — flips its results.tsv row to status=rollback without rewriting git history. Use when a previously-accepted round is later revealed to regress. --dry-run reports what would change without applying.

`zyme verify`

zyme verify [--reps N] [--threads 1,4,8] [--tiers tiny,medium,large,ood_large]

Validation validation cube. Each cell = (tier × threads) → PASS / SOFT (within scaling-tax tolerance) / HARD (regression). Renders an ASCII matrix. Persists rows to verify.tsv.

`zyme attest`

zyme attest [--reps N] [--tiers tiny,medium,large,ood_large,ood_xlarge]

Packaging ship gate — the command you run to verify a patch before shipping. Runs the full tier sweep (baseline + patched timing + metric gate) at the declared reps and writes package_verify.tsv, which you commit alongside the patch.

`zyme status`

zyme status [--task-dir <path>] [--last <N>] [--phase optimize|validate|memory|all]

decision rounds: 47/50   pending: 0   keep: 12   discard: 35
best speedup: 4.8x (tiny), 3.2x (medium)
pipeline: pipeline/run.py at commit ab12cd
last 5 decisions:
   47  keep    vectorize inner loop                                   +0.4x
   46  discard try simd intrinsics — broke on small tiers
   ...

`zyme scan`

zyme scan [<workspace_root>]

Workspace dashboard — every task in the tree with round count, best speedup, status. Useful for managing many in-flight optimization tasks.

Common flags

--version is the only true top-level flag. The flags below are defined on the subcommands that accept them, not globally:

Flag	Effect
`--task-dir <path>`	Run a task-scoped command from outside the task dir (CI; supervisor agents). Workspace-level commands (`init`, `scan`, `dispatch`, …) do not accept it
`--json`	Emit machine-readable JSON on the read-only commands that support it (e.g. `profile`, `scan`, `audit`, `cost`)

Exit codes

Code	Meaning
0	Success
1	User error — bad args, missing file, wrong state (fix and retry)
2	Validation / phase-discipline / operation failure — e.g. a gate failure, missing `task.yaml`, a failed dataset migration, or `zyme run` blocked by task-definition changes outside `--setup`
3	Resource error — out of memory, disk full, watchdog timeout

Environment variables

Var	Effect
`ZYME_TIER`	Override the tier evaluate.py/.R sees (used internally; rarely set by hand)
`ZYME_REFERENCE_DIR` / `ZYME_TEST_DIR` / `ZYME_DATA_PATH` / `ZYME_TASK_DIR`	Set by the runner before invoking evaluate.py/.R / pipeline/run.py/.R
`ZYME_THREADS`	Thread count, read by run_task.sh; highest precedence in the `auto_threads` picker (chain: `ZYME_THREADS` > `AUTOZYME_THREADS` > `OMP_NUM_THREADS` > `AUTOZYMER_THREADS`)
`AUTOZYME_DISABLED`	Set to `1` to suppress activation entirely (session-wide opt-out)
`AUTOZYME_THREADS`	Thread count for the `auto_threads` picker (user-facing; honored below `ZYME_THREADS`)
`AUTOZYMER_THREADS`	Legacy spelling of `AUTOZYME_THREADS`; still honored by the picker as a last-resort fallback
`NUMBA_NUM_THREADS`	Read by numba at module import; set BEFORE `import autozyme` to take effect

zyme CLI reference

Core loop — edit / measure / decide

Measurement — references and verification

Analysis — read-only dashboards

Workflow — multi-task / templates

Utility — one-shot tools

High-traffic commands in detail

zyme init

zyme run

zyme accept

zyme reject

zyme dryrun

zyme profile

zyme rollback

zyme verify

zyme attest

zyme status

zyme scan