CLI reference

Every command below is real and current — run epochix <command> --help for the full option list, which is generated from the code itself.

If the dashboard looks empty or the grade looks wrong, start with epochix check. It reports what the parsers can and cannot read from your log and tells you what to add.

epochix --version prints the installed version.

---

epochix run

Parse a training log and visualise it. This is the default action, so epochix train.log and epochix run train.log are the same thing.

epochix run train.log

Useful options:

Option	What it does
--headless	Do not open a browser. Use in CI.
--export html\|pdf\|md\|json	Write a report (requires --headless).
--output, -o	Where to write that report. Parent directories are created. Defaults to <run_id>.<format> in the current directory.
--port, -p	Server port (default 7860).
--task, -t	Force the task type instead of detecting it.
--name, -n	Give the run a readable name.
--no-llm	Disable the optional LLM fallback parser.

Watch a run as it trains by piping into epochix. Piped input is detected automatically, and --live forces it:

python train.py | epochix
python train.py | epochix --live

To follow a file that is still being written, or a log on another machine, see --tail and --ssh in epochix run --help.

epochix demo

See the dashboard without training anything of your own. Each demo is the recorded console output of a real training run; the script that produced it sits beside the log in the repository's demo/ folder.

epochix demo
epochix demo yolov8
epochix demo keras

Demo	The run
seq2seq (default)	A GRU encoder-decoder with attention translating French to English, trained with PyTorch Lightning. It overfits mildly towards the end, and the dashboard says so.
yolov8	YOLOv8n fine-tuned with Ultralytics on COCO128, the 128-image tutorial set. Its validation images are its training images, so the mAP shows fit, not generalisation.
keras	A small CNN on scikit-learn's handwritten digits, trained with Keras 3. It is still setting new bests at its last epoch, and the grade says so.

epochix check

Explain what epochix can read from a log — and what to add so it can read more. Nothing is stored and nothing is served; this only reports.

epochix check train.log

Reach for this first when a run produced no story, an unexpected grade, or an empty architecture panel. It names the metric the run is told by, and which grade thresholds apply — the built-in ones, or your .epochix.yaml and whether any entry in it applies to this log.

epochix serve

Start the server on its own, without processing a run.

epochix serve --port 7860

If the port is taken, epochix says so and suggests another rather than raising a traceback. Binding a non-loopback --host without EPOCHIX_AUTH_TOKEN prints a warning — see Configuration.

epochix list

List saved runs, newest first.

epochix open

Open a saved run in the browser by run ID.

epochix export

Export a saved run as HTML, PDF, Markdown, or JSON.

epochix export <run_id> --format md --output report.md

PDF needs the extra: pip install 'epochix[pdf]'.

epochix compare

Compare two or more saved runs as a document: the same explanation the dashboard's comparison view gives — who finished ahead, or why the runs cannot honestly be ranked — and each run's grade, final and best value.

epochix compare <run_a> <run_b> --output comparison.md
epochix compare <run_a> <run_b> --format pdf --output comparison.pdf

Markdown prints to the terminal without --output. The PDF adds the runs' curves overlaid on one chart — only when they measure the same metric, since the text refuses to rank runs that do not — and is written to comparison.pdf without --output. It is told in the first run's language unless --locale says otherwise. The comparison view in the dashboard has both downloads beside its race GIF.

epochix race

Animate several runs racing on one metric, as a GIF for a slide.

epochix race <run_a> <run_b> --metric val_accuracy --output race.gif

epochix prune

Delete runs older than a given age. Check first with --dry-run:

epochix prune --older-than 30d --dry-run

epochix config

Show or set configuration values. See Configuration.

epochix config show
epochix config set port 8080

epochix import-tensorboard

Tell the story of a run you already logged to TensorBoard. The scalars are read straight off disk: no account, no network. See Already using W&B, TensorBoard, or plain logs?.

epochix import-tensorboard runs/exp1

epochix import-wandb

Tell the story of a Weights & Biases run. Give it your local wandb/ directory, one run directory inside it, or a .wandb file, and nothing leaves your machine. Give it entity/project/run_id to fetch from the W&B servers instead, which needs your API key in WANDB_API_KEY.

epochix import-wandb wandb/
epochix import-wandb my-team/my-project/abc123

epochix doctor

Print diagnostics to paste into a bug report: versions, which optional features are installed, your accelerator and whether activation capture works on it, whether the dashboard shipped, and how many runs are stored. It prints no run names, file paths or log contents.

epochix doctor