CLI Reference¶
The mech CLI is the primary interface to the platform. All commands are implemented in
src/mech_interp/cli.py via Typer.
Quick reference¶
Core commands¶
mech run¶
Run a single experiment spec.
mech run --name <spec-name>
mech run --spec experiments/polysemanticity.yaml
mech run --name polysemanticity-sae-layer0 --dry-run
Options:
| Flag | Default | Description |
|---|---|---|
--name |
— | Experiment name (resolves from experiments/) |
--spec |
— | Path to a YAML spec |
--dry-run |
false | Validate spec without executing |
--force |
false | Re-run even if a result exists |
mech sweep¶
Generate and optionally execute a parameter sweep.
mech sweep \
--base experiments/polysemanticity.yaml \
--axis "parameters.seed=1,2,3,4,5" \
--output experiments/sweeps/my_sweep.yaml \
--execute
Options:
| Flag | Description |
|---|---|
--base |
Base YAML spec to sweep over |
--axis |
Axis spec in key=v1,v2,... format; repeatable for multi-axis sweeps |
--output |
Write generated sweep YAML to this path |
--execute |
Run all generated specs immediately |
mech validate¶
Run a fast smoke test to verify the platform is working.
Checks: TransformerLens forward pass, storage layer, experiment registry.
mech cockpit¶
Open the local web cockpit (FastAPI + Jinja2) for browsing runs, artifacts, and reports.
mech demo¶
Launch the Gradio interactive demo.
Requires: pip install mech-interpretability[gradio]
Analysis commands¶
mech analyze-sae-stability¶
Compute pairwise seed stability across an SAE sweep.
mech analyze-sae-stability \
--sweep experiments/sweeps/sae_seed_stability.yaml \
--output artifacts/stability_report.json \
--live-only
Options:
| Flag | Description |
|---|---|
--sweep |
Path to sweep YAML with multiple runs |
--output |
Write JSON stability report to this path |
--live-only |
Restrict matching to live (non-dead) features only |
mech analyze-feature-splits¶
Compute feature splitting analysis between a parent and child SAE run.
mech analyze-sae¶
Analyze a single SAE run: dead features, decoder norms, top activating prompts.
mech sae-scale-report¶
Generate a detailed scale report for a large SAE run.
mech label-features¶
Auto-label SAE features using a heuristic or LLM labeler.
mech label-features --run-id 51 --labeler heuristic --max-features 20
mech label-features --run-id 51 --labeler anthropic
mech label-features --run-id 51 --labeler ollama
mech compare-runs¶
Compare two runs side-by-side.
Data commands¶
mech download-corpus¶
Download a named corpus to a local JSONL file.
mech download-corpus --name openwebtext --max-documents 100 --output data/prompts/openwebtext.jsonl
mech download-corpus --name pile-1k --max-documents 1000 --output data/prompts/pile-1k.jsonl
mech list-saes¶
List SAEs available in the SAE registry (pre-trained weights).
mech download-sae¶
Download a pre-trained SAE from the registry.
Run management commands¶
mech runs¶
List all stored runs.
mech inspect-run¶
Show full details for a specific run.
mech export-run¶
Export a run's artifacts as a ZIP.
mech archive-runs¶
Archive (compress) old run artifacts.
mech query-runs¶
SQL-style query over the run database.
Orchestration commands¶
mech propose-followups¶
Use the AI planner to propose follow-up experiment specs from recent runs.
mech propose-from-run¶
Propose follow-ups from a specific run's results.
mech iterate¶
Run the full agentic iterate loop: propose, execute, analyze, repeat.
mech iterate-from-run¶
Start an iterate loop seeded from an existing run.
mech preflight¶
Validate that a run spec is feasible given current memory and hardware.
Utility commands¶
mech config¶
Show the current platform configuration.
mech providers¶
Check which model providers are available.
mech init-store¶
Initialize the SQLite artifact store at ~/.mech_interp/runs.db.
mech estimate-activations¶
Estimate activation cache size for a given spec before running.