CLI Reference

Status: Current Last updated: 2026-09-16 09:47 EDT

This page documents the current public batchalign3 CLI surface. For anything you are scripting against, confirm with batchalign3 <command> --help.

For detailed input/output patterns and mutation behavior per command, see Command I/O Parity.

Command shape

batchalign3 [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS] [PATHS...]

Global options go before the command name.

Global options

BA2 compatibility flags (--memlog, --mem-guard, --adaptive-workers, --pool, --shared-models, etc.) have been removed. If your scripts use them, remove them.

Engine selection

These are per-command flags, not global ones: they go AFTER the command name, like batchalign3 transcribe in/ --asr-engine paraformer.

Each flag’s --help lists every value it accepts, derived from the engine enum itself, so the advertised set and the accepted set are the same list. An unrecognized name is rejected while parsing, naming what you typed and suggesting the nearest valid value.

The older --asr-engine-custom / --fa-engine-custom / --utr-engine-custom flags still work and are hidden from help. They exist because each visible flag used to advertise only some of its engines, which left the rest reachable only through a second, differently-named flag: that is how the Cantonese engines stayed hidden from the people who needed them. Prefer the flags above.

The asr / fa / utr / translate keys of --engine-overrides also select an engine, and take precedence over the flags. Use the flags for ordinary work; the keys exist so one shared option can pin engines across a batch.

utr was missing from that set until 2026-08-06: it parsed, was forwarded to the Python worker as an opaque extra, and was ignored by everything, so a user who wrote it saw their choice silently dropped.

Sequential mode

--sequential gives you the simplest possible execution path, similar to batchalign2’s direct mode. One worker per task type, files processed one at a time, no concurrency infrastructure:

batchalign3 morphotag corpus/ -o output/ --sequential

What it does:

• Forces --workers 1 and --no-server
• Disables the memory gate (no cross-process coordination)
• Keeps the worker alive for the entire run (no idle timeout kills)
• Preserves the utterance cache (repeated runs benefit from cached results)

When to use it:

• Processing a handful of files on a laptop
• Debugging pipeline issues (predictable, single-threaded execution)
• Environments where memory auto-tuning is unwanted

When NOT to use it:

• Large corpus runs (50+ files), the default parallel mode is 3-5× faster
• Fleet machines with warm workers, use the server instead

--sequential is incompatible with --server (mutually exclusive).

Dashboard browser auto-open

On macOS, when you run a processing command interactively (e.g., batchalign3 transcribe corpus/ output/), the CLI automatically opens the job’s dashboard page in your default browser. This lets you monitor progress in real time.

Direct local execution does not submit an HTTP job, so there is no dashboard page to open. In that mode, --open-dashboard is a no-op and the CLI shows local terminal progress inline instead.

The dashboard auto-open is only triggered when:

• Running on macOS (no-op on Linux/Windows)
• stderr is connected to an interactive terminal (TTY)
• --no-open-dashboard was not passed
• The BATCHALIGN_NO_BROWSER environment variable is not set

It will not fire in non-interactive contexts: cron jobs, CI pipelines, SSH sessions without a display, piped output, or scripts. To suppress it explicitly in interactive sessions, pass --no-open-dashboard.

Common path-processing options

The core processing commands documented below all accept:

When exactly two positional paths are provided, the CLI still accepts the legacy input/output directory form. For new scripts, prefer -o/--output.

--file-list format

--file-list FILE reads input paths from a plain-text UTF-8 file, one path per line:

• Blank lines and lines beginning with # are ignored; whitespace around each path is trimmed.
• A relative path resolves against the directory containing the list file, not the directory you run the command from. Absolute paths are used as written.
• A path naming a directory is expanded exactly like a positional directory argument: matching files are discovered recursively beneath it.
• The input set is de-duplicated, keeping the first occurrence. A file listed twice, spelled two ways (a.cha, ./a.cha, an absolute path), or reached both directly and through a listed directory is processed once.
• Every entry must exist when the command runs. A missing entry is a usage error (exit code 2) naming the list file and line, for example lists/rerun.txt:3: input path does not exist: lists/corpus/missing.cha.

# lists/rerun.txt: entries are relative to lists/
corpus/session-01.cha
corpus/session-02.cha

# a whole directory, and an absolute path
corpus/follow-up/
/data/project/extra/session-09.cha

# Run align on every listed input (in place, against a remote server)
batchalign3 --server http://your-server:8001 align --file-list lists/rerun.txt

To process a large list in smaller batches, split it into chunk files in the same directory as the original list (for example, run split -l 10 rerun.txt batch- inside that directory) so relative entries keep resolving against the same place, then run batchalign3 align --file-list <chunk> on each chunk sequentially.

--file-list cannot be combined with positional PATHS arguments; the CLI rejects the combination. Without -o/--output, every listed input is processed in place (output overwrites input); with -o DIR, results are written under DIR exactly as for positional inputs.

For batched text-NLP commands (morphotag, utseg, translate, coref), large --file-list runs may not show file-by-file on-disk rewrites while the invocation is still running. The command can batch/stage work internally and then commit the in-place writes when the current invocation finishes. If you need visible write-through during a long rerun, split the list into smaller chunks and run those chunks sequentially.

Processing commands

Each processing command has a dedicated page with full options, a pipeline diagram, examples, and gotchas. Click the command name for complete documentation.

CHAT-mutation commands (input .cha → output .cha)

Audio-input commands (input audio → new files)

Operational commands

setup

Initialize ~/.batchalign.ini:

batchalign3 setup
batchalign3 setup --non-interactive --engine whisper
batchalign3 setup --non-interactive --engine rev --rev-key <KEY>

Options:

logs

batchalign3 logs
batchalign3 logs --last
batchalign3 logs --export
batchalign3 logs --clear

Key options:

serve

batchalign3 serve start --foreground
batchalign3 serve status
batchalign3 serve stop

serve start key options:

jobs

batchalign3 jobs --server http://myserver:8000
batchalign3 jobs --server http://myserver:8000 <JOB_ID>
batchalign3 jobs <JOB_ID>
batchalign3 jobs --json <JOB_ID>
batchalign3 jobs cancellations <JOB_ID>

With --server, lists or inspects remote jobs. Without --server, inspects the local job artifact directory for post-failure debugging. Pass --json for machine-readable output.

The cancellations subcommand prints the cancellation audit history for a single job, every cancel attempt is recorded with source (tui / api / dashboard / staging / signal), host, pid, reason, and in_flight_filename. Use this when a user reports “I didn’t cancel that job.”

cache

batchalign3 cache stats
batchalign3 cache clear --yes
batchalign3 cache clear --all --yes

BATCHALIGN_ANALYSIS_CACHE_DIR and BATCHALIGN_MEDIA_CACHE_DIR relocate the underlying caches for isolated runs. BA2-compatible flag forms cache --stats and cache --clear are still accepted.

openapi

batchalign3 openapi -o openapi.json
batchalign3 openapi --check --output openapi.json

--check exits non-zero when the target file does not match the generated schema.

models

Two subcommands:

See Models Training Runtime ADR.

ipc-schema

batchalign3 ipc-schema -o schemas/
batchalign3 ipc-schema --check --output schemas/

Emits JSON Schema for Rust→Python IPC types. Without -o, schemas are written to stdout as a single JSON object. With --check, exits non-zero on schema drift against the target directory.

bench

batchalign3 bench <COMMAND> <IN_DIR> <OUT_DIR> [--runs N]
batchalign3 bench align corpus/ out/ --runs 3 --dataset eng-childes-v1
batchalign3 bench align corpus/ out/ --use-cache

Benchmark command execution time across repeated runs. <COMMAND> is one of: align, transcribe, transcribe_s (with diarization), morphotag, translate, utseg, benchmark, opensmile, coref, compare. Distinct from the benchmark top-level command, which measures ASR word accuracy.

doctor

batchalign3 doctor
batchalign3 doctor --lang yue --format json
batchalign3 doctor --explain memory_gate_mb
batchalign3 doctor --warnings-as-errors

Pre-flight diagnostic that spawns a test worker, sends known inputs through the morphosyntax pipeline, and validates the output structure. Catches machine-specific issues (stale models, missing processors, MWT quirks) before they become production failures.

replay

batchalign3 replay <DUMP_FILE>
batchalign3 replay --lang yue path/to/failed_ipc_*.json

Replay a captured failed IPC request against a fresh worker. Takes a dump file from ~/.batchalign3/debug/ and sends the exact request to a new worker, reporting the response. Useful for reproducing field failures locally.

eval

batchalign3 eval l2-morphotag <ARGS>
batchalign3 eval utr-alignment --chat <CHAT> --tokens <JSON> --output <JSON>
batchalign3 eval utseg-replay post-chat --input-chat <CHAT> --evidence <JSON> --output-chat <CHAT>
batchalign3 eval utseg-replay pre-asr --asr-response <JSON> --evidence <JSON> --output-chat <CHAT> [--media-name <NAME>] [--wor]

Evaluation subcommands. Currently:

version

batchalign3 version

Prints version and build information.

Exit codes

batchalign3 uses stable non-zero exit code categories:

Exit code 1 is reserved for unexpected failures outside the typed categories.

A server that reports another build than the CLI’s, or no build, is refused before anything is submitted, with exit code 5; see Server Mode: build identity check.

This page last changed: 2026-09-16 (commit 197c81e6). The whole book last changed: 2026-09-16 (commit 34d249d8).