# CLI Reference ## Shortest useful command ```sh go run ./cmd/seriatim merge \ --input-file speaker-a.json \ --input-file speaker-b.json \ --output-file merged.json ``` ## Command overview | Command | Purpose | | --- | --- | | `merge` | Merge one or more raw transcript JSON inputs into one seriatim artifact. | | `trim` | Keep or remove segment IDs from an existing seriatim artifact. | | `normalize` | Canonicalize transcript-like JSON into a seriatim artifact. | | `render` | Render an existing seriatim artifact as Markdown. | Root usage: ```text seriatim [command] ``` ## Global flags | Flag | Description | | --- | --- | | `-h, --help` | Show help. | | `-v, --version` | Show build version. | ## `merge` Usage: ```text seriatim merge [flags] ``` Flags: | Flag | Required | Default | Description | | --- | --- | --- | --- | | `--input-file stringArray` | Yes, repeat at least once | none | Input transcript JSON file(s). | | `--output-file string` | Yes | none | Output transcript JSON file path. | | `--report-file string` | No | none | Optional report JSON path. | | `--speakers string` | No | none | Speaker-map YAML file. | | `--autocorrect string` | No | none | Autocorrect YAML file. | | `--input-reader string` | No | `json-files` | Input reader module name. | | `--output-modules string` | No | `json` | Comma-separated output module names. | | `--output-schema string` | No | `seriatim-intermediate` | Output schema name: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. | | `--preprocessing-modules string` | No | `validate-raw,normalize-speakers,trim-text` | Comma-separated preprocessing module names, run in order. | | `--postprocessing-modules string` | No | `detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output` | Comma-separated postprocessing module names, run in order. | | `--coalesce-gap string` | No | `3.0` | Non-negative seconds for coalescing and overlap-resolution context. | `merge` behavior and validation: - Unknown input reader, preprocessing module, postprocessing module, or output module fails the command. - Preprocessing order must satisfy module state requirements (`raw` -> `canonical`); invalid order fails. - Input files are validated, deduplicated, normalized, then sorted for deterministic processing. - Optional report output is written only when `--report-file` is set. - When `--output-schema` is omitted, schema resolution is: `SERIATIM_OUTPUT_SCHEMA` -> default `seriatim-intermediate`. ## `trim` Usage: ```text seriatim trim [flags] ``` Flags: | Flag | Required | Default | Description | | --- | --- | --- | --- | | `--input-file string` | Yes | none | Input seriatim artifact JSON file. | | `--output-file string` | Yes | none | Output transcript JSON file path. | | `--keep string` | Exactly one of `--keep` / `--remove` | none | Segment ID selector to keep. | | `--remove string` | Exactly one of `--keep` / `--remove` | none | Segment ID selector to remove. | | `--output-schema string` | No | preserve input artifact schema | Output schema override: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. | | `--report-file string` | No | none | Optional report JSON path. | | `--allow-empty` | No | `false` | Allow output with zero segments. | Selector rules: - IDs must be positive integers. - Single IDs and inclusive ranges are supported: `1`, `1-10`. - Comma-separated selectors are supported: `1-10,15,20-25`. - Whitespace around commas and hyphens is allowed. - Descending ranges (example `10-1`) are invalid. - Duplicates and overlapping ranges are normalized as a union. `trim` behavior: - Input must already be a valid seriatim artifact (not raw merge input JSON). - Output keeps transcript order from input and renumbers retained segment IDs sequentially. - If `--output-schema` is omitted, the input artifact schema is preserved. - `trim` never runs merge preprocessing/postprocessing modules. ## `normalize` Usage: ```text seriatim normalize [flags] ``` Flags: | Flag | Required | Default | Description | | --- | --- | --- | --- | | `--input-file string` | Yes | none | Input transcript JSON file. | | `--output-file string` | Yes | none | Output transcript JSON file path. | | `--output-schema string` | No | `seriatim-intermediate` | Output schema name: `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. | | `--output-modules string` | No | `json` | Comma-separated output module names (`json` only). | | `--report-file string` | No | none | Optional report JSON path. | `normalize` input shapes: - Object with top-level `segments` array. - Bare top-level segment array. `normalize` behavior: - Sorts deterministically and reassigns output IDs sequentially from `1`. - Fills missing/blank speakers with `Unknown_Speaker`. - Repairs/sanitizes timing fields deterministically; rejects invalid repaired timing. - Drops segments with missing or blank text. - Does not run merge modules. - When `--output-schema` is omitted, schema resolution is: `SERIATIM_OUTPUT_SCHEMA` -> default `seriatim-intermediate`. ## `render` Usage: ```text seriatim render [flags] ``` Flags: | Flag | Required | Default | Description | | --- | --- | --- | --- | | `--input-file string` | Yes | none | Input seriatim artifact JSON file. | | `--output-file string` | Yes | none | Rendered output file path. | | `--format string` | Yes | none | Output format. Current supported value: `markdown`. | | `--title string` | No | `Transcript` | Markdown document title. | | `--include-timestamps` | No | `true` | Include `[HH:MM:SS–HH:MM:SS]` per segment. | | `--include-segment-ids` | No | `false` | Include `[#id]` marker per segment. | | `--include-metadata` | No | `false` | Include artifact metadata block near the top. | `render` behavior: - Input must be a valid existing seriatim output artifact (`seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`). - Raw WhisperX-style JSON is rejected. - `render` does not execute merge/trim/normalize transformations. - `render` has no `--report-file` output in the current implementation. - Markdown output is deterministic for the same input artifact and render flags. - Category names are not printed directly; `background`, `backchannel`, and `filler` only influence italics. ## Common workflows Merge with a speaker map and report output: ```sh go run ./cmd/seriatim merge \ --input-file examples/minimal-merge/input-alice.json \ --input-file examples/minimal-merge/input-bob.json \ --speakers examples/minimal-merge/speakers.yml \ --output-file /tmp/seriatim-example-merge.json \ --report-file /tmp/seriatim-example-merge-report.json ``` Trim to a segment subset: ```sh go run ./cmd/seriatim trim \ --input-file examples/trim/input-full.json \ --output-file /tmp/seriatim-example-trim.json \ --keep "1-2" ``` Normalize an external transcript JSON file: ```sh go run ./cmd/seriatim normalize \ --input-file examples/normalize/object-with-segments.json \ --output-file /tmp/seriatim-example-normalize-object.json ``` Render an existing artifact as Markdown: ```sh go run ./cmd/seriatim render \ --input-file examples/render/input-intermediate.json \ --output-file /tmp/seriatim-example-render.md \ --format markdown ``` ## Exit and errors - Commands return exit code `0` on success. - On error, the CLI prints one error line to stderr and exits with status `1`. - Cobra usage text is silenced on runtime errors; use `--help` for command usage. ## Related docs - Configuration reference: [config.md](config.md) - Operations guide: [operations.md](operations.md) - Troubleshooting: [troubleshooting.md](troubleshooting.md) - Integration notes: - [integrations/whisperx-json.md](integrations/whisperx-json.md) - [integrations/output-schemas.md](integrations/output-schemas.md) - Synthetic examples: [../examples/README.md](../examples/README.md) - Public output schemas: - [../schema/minimal-output.schema.json](../schema/minimal-output.schema.json) - [../schema/intermediate-output.schema.json](../schema/intermediate-output.schema.json) - [../schema/full-output.schema.json](../schema/full-output.schema.json)