seriatim/docs/cli.md

CLI Reference

Shortest useful command

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:

seriatim [command]

Global flags

Flag	Description
-h, --help	Show help.
-v, --version	Show build version.

merge

Usage:

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:

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:

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:

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.
• 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:

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:

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:

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:

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
• Operations guide: operations.md
• Troubleshooting: troubleshooting.md
• Integration notes:
  • integrations/whisperx-json.md
  • integrations/output-schemas.md
• Synthetic examples: ../examples/README.md
• Public output schemas:
  • ../schema/minimal-output.schema.json
  • ../schema/intermediate-output.schema.json
  • ../schema/full-output.schema.json