CLI reference

Status: Published exact 1.2.0 stable release; historical input behavior retained

This document is the maintained CLI authority. The public command names and behavior described here form the stable v1.0.0 contract published through immutable tag v1.0.0 and the verified GitHub Release. The exact generated help under internal/cli/testdata/help/ and executable documentation tests are checked against this reference.

Current stable release

The official v1.2.0 executable reports exact 1.2.0 from version and schema --version, and emits its byte-identical immutable release schema. Its native encode uses that identity and official producer version. Exact historical 1.1.0 and 1.0.0 Cue JSON uses local historical structure/semantics through every promised command, preserving input identity, producer and source truth; inspection reports its loaded identity. Unknown, mismatched and former development identities and corrupt source envelopes fail before publication. Released v1.1.0 and v1.0.0 executables reject new 1.2.0 output, including documents encoded from its existing text formats; there is no historical-output selector.

The frozen bounded ASS/SSA profile provides stable native detection/ingest, textual rendering, all twelve conversion directions, validation, privacy-safe inspection, exact restoration and shared help/completion discovery. Official new output declares stable with ingest, render and restore true and OCR false. Exact-current schema_only and complete experimental declarations remain accepted observations independent of installed codec availability and are never rewritten on load. Version 1.2.0 is tagged, publicly released and independently verified. Historical 1.1.0 schema hosting and production deployment completed through #76/#67, with protected deployment repair through #78. S035 prepares matching 1.2.0 production schema/documentation; #86 remains open until authorized exact-main deployment and independent live verification pass after the owner merges the reviewed PR.

Invocation, streams, and status

The published executable and current source use exact 1.2.0 for version/schema discovery and new encode, with local historical 1.1.0 and 1.0.0 validation. Optional consumer attributions and media timing add count-only inspection and runtime media-conflict warnings without changing archived source observations. validate reports media boundary state when consumer data exists. Native render and conversion omit consumer fields with complete warnings/losses; strict refuses before publishing. The former 1.2.0-dev identity rejects. These additions ship in v1.2.0 and are absent from historical v1.1.0 packages.

The root form is cueson [global options] <command>. Global options may appear before or after the command until the -- delimiter ends option processing. User paths are literal; Cueson does not expand globs, tildes, or environment-variable syntax.

• -q, --quiet: suppress informational and success diagnostics while retaining warnings and errors.
• --silent: suppress every non-error diagnostic while retaining errors.
• --no-color: disable diagnostic color. NO_COLOR is honored, and non-terminal diagnostics are uncolored.
• -h, --help: print complete explicit help to stdout and exit successfully.
• --: end option processing so following operands remain literal.

Stdout contains only a requested payload or explicit help. Diagnostics, warnings, errors, and error-associated short usage use stderr. Quiet and silent never suppress an explicitly requested stdout payload. Cueson emits no decorative banner or emoji. Generated text is UTF-8 without BOM and LF-only unless exact restoration reproduces different preserved source bytes.

• Exit code 0: the command or explicit help completed successfully; warnings may be present.
• Exit code 1: an accepted operation failed during processing, cancellation, validation, integrity checking, strict rejection, capability handling, output delivery, or runtime I/O.
• Exit code 2: command syntax, an operand, an option, or a deterministic pre-execution path or environment requirement was invalid.

Existing output is never replaced implicitly. A filesystem destination requires --force before Cueson will replace an existing regular file. --force does not permit replacing a directory, symbolic link, device, or other non-regular entry, and it is invalid when output is stdout.

The root help lists exactly nine commands: encode, restore, render, convert, validate, inspect, schema, version, and completion.

encode

cueson [global options] encode [options] INPUT

encode captures one bounded regular SubRip, WebVTT, or bounded ASS/SSA input, derives common and native cue data, validates the resulting document, and preserves the exact source bytes in Cue JSON.

• -o, --output PATH: write Cue JSON to PATH; without an output selection, the destination is INPUT.cueson.json. --output - selects stdout.
• -f, --force: replace an approved existing regular filesystem output.
• --format FORMAT: select auto, srt, vtt, ass, or ssa; subrip aliases srt, and webvtt aliases vtt.
• --encoding NAME: select utf-8, utf-8-bom, utf-16le, utf-16be, windows-1252, or iso-8859-1. Accepted aliases are utf8; utf8-bom and utf-8-sig; utf16le and utf-16-le; utf16be and utf-16-be; windows1252 and cp1252; and iso8859-1, latin1, and latin-1.
• --pretty: indent Cue JSON output.
• --stdout: write Cue JSON to stdout; it is mutually exclusive with a filesystem output.
• --no-speaker-detection: disable conservative derived Name: speaker observations.

WebVTT and ASS/SSA accept UTF-8 only, including BOM-specific UTF-8 selection when the input has the matching BOM. SubRip accepts automatic UTF-8, BOM-marked UTF-16, strongly evidenced BOM-less UTF-16, and explicitly selected legacy single-byte encodings. Input is limited to 64 MiB. ASS/SSA native Actor/Name speaker observations survive --no-speaker-detection; that option controls derived speaker detection. Malformed recognized scripted candidates reject before publication regardless of extension or an explicit incompatible selector.

For a filesystem output, success exits 0 with empty stdout and only source warnings on stderr. The executable README scenario is:

cueson encode --pretty --output quickstart/document.cueson.json testdata/fixtures/conversion/srt-loss-free/source/input.srt

restore

cueson [global options] restore [options] INPUT.cueson.json

restore validates the source envelope and recreates its exact asset bytes without invoking a codec or rendering the structured model. Cue JSON input is bounded at 1 GiB, and encode refuses to publish a larger representation, so every document produced by the CLI remains within the exact-restore boundary.

• -o, --output PATH: restore a single asset to a separately validated literal path.
• --output-dir DIR: restore all assets beneath an existing directory using their safe stored basenames.
• -f, --force: replace approved existing regular files after the complete restoration plan passes preflight.
• --strict-metadata: require every captured timestamp to be restored; an unsupported value rolls back the operation and exits 1.
• --no-metadata: skip timestamp restoration. It is mutually exclusive with --strict-metadata.

Without a destination option, one asset uses its safe stored basename in the current directory. --output and --output-dir are mutually exclusive, and multi-asset documents require --output-dir. Parents must already exist. Restoration validates canonical base64, length, SHA-256, safe basenames, portable collisions, and the complete destination plan before publication. It does not claim crash atomicity or cross-process isolation.

Success writes no stdout. Stderr contains only metadata warnings allowed by the global filters. The executable README scenario is:

cueson restore --no-metadata --output quickstart/restored.srt quickstart/document.cueson.json

render

cueson [global options] render [options] INPUT.cueson.json --to FORMAT

render validates Cue JSON and serializes its structured cue model in the document's matching native format. It is intentionally distinct from exact restoration.

• --to FORMAT: select srt, vtt, ass, or ssa; subrip aliases srt, and webvtt aliases vtt. ASS/SSA textual rendering follows the stable bounded profile.
• -o, --output PATH: write native output to a filesystem path instead of stdout; --output - selects stdout.
• -f, --force: replace an approved existing regular filesystem output.
• --strict: reject known non-representable, ambiguous, or preserved nonconforming model content before publication.

The target must match the document's native format; use convert for another target. Success writes canonical native bytes to stdout unless a filesystem output is selected. Warnings and errors use stderr.

cueson render --to srt --output quickstart/rendered.srt quickstart/document.cueson.json

convert

cueson [global options] convert [options] INPUT --to FORMAT

convert accepts Cue JSON, SubRip, WebVTT, ASS, or SSA and serializes a private target projection in a distinct supported native format. All twelve distinct directions are implemented; ASS/SSA follow the stable bounded profile. Cue JSON recognition has precedence; actual JSON containers or .json-named invalid content do not fall through to a native codec. Recognized bracketed ASS/SSA content reaches guarded native classification even with a conflicting filename.

• --to FORMAT: select srt, vtt, ass, or ssa; subrip aliases srt, and webvtt aliases vtt.
• --from FORMAT: select auto, cueson, srt, vtt, ass, or ssa; json and cue-json alias cueson, subrip aliases srt, and webvtt aliases vtt.
• --encoding NAME: for native input, select utf-8, utf-8-bom, utf-16le, utf-16be, windows-1252, or iso-8859-1. Accepted aliases are utf8; utf8-bom and utf-8-sig; utf16le and utf-16-le; utf16be and utf-16-be; windows1252 and cp1252; and iso8859-1, latin1, and latin-1.
• -o, --output PATH: write native output to a filesystem path instead of stdout; --output - selects stdout.
• -f, --force: replace an approved existing regular filesystem output.
• --strict: compute the complete loss report and reject before rendering or publication when any known loss exists.
• --no-speaker-detection: disable derived speaker observations for native input.

Normal conversion writes all representable target bytes and reports every known omission, degradation, or ambiguity on stderr. Loss records have a stable code, severity, kind, source and target format, portable JSON Pointer, and bounded occurrence context; they never enter Cue JSON or expose source bytes or local identity. Fatal target incompatibility fails in normal and strict modes. The complete mapping is maintained in the conversion contract.

ASS/SSA native sources accept UTF-8 only. Scripted targets use deterministic defaults and checked nearest-centisecond rounding (ties upward), report each changed endpoint, and reject collapsed intervals or unsafe literal controls. Drawing-only or unreadable scripted dialogue cannot become text output. Conversion preserves original source assets and uses an internal constructed-target boundary; it never emits fabricated target Cue JSON provenance.

cueson convert --strict --no-speaker-detection --to vtt --output quickstart/converted.vtt testdata/fixtures/conversion/srt-loss-free/source/input.srt
cueson convert --strict --to srt --output quickstart/converted.srt testdata/fixtures/conversion/webvtt-loss-free/source/input.vtt

validate

cueson [global options] validate [options] INPUT

validate accepts Cue JSON, SubRip, WebVTT, or bounded ASS/SSA and performs the complete applicable validation stack without creating or printing a payload.

• --format FORMAT: select auto, cueson, srt, vtt, ass, or ssa; json and cue-json alias cueson, subrip aliases srt, and webvtt aliases vtt.
• --encoding NAME: for native input, select utf-8, utf-8-bom, utf-16le, utf-16be, windows-1252, or iso-8859-1. Accepted aliases are utf8; utf8-bom and utf-8-sig; utf16le and utf-16-le; utf16be and utf-16-be; windows1252 and cp1252; and iso8859-1, latin1, and latin-1.

Cue JSON prohibits --encoding; WebVTT and ASS/SSA accept only compatible UTF-8 selections. Auto mode gives valid Cue JSON precedence, then uses native content evidence and extension evidence. Success exits 0, writes empty stdout, and emits one success diagnostic plus any ordered warnings on stderr. Quiet suppresses success; silent also suppresses warnings.

cueson validate testdata/fixtures/webvtt/minimal/source/minimal.vtt

inspect

cueson [global options] inspect [options] INPUT

inspect uses the same classification and validation depth as validate, then emits a privacy-bounded structural report.

• --format FORMAT: select auto, cueson, srt, vtt, ass, or ssa; json and cue-json alias cueson, subrip aliases srt, and webvtt aliases vtt.
• --encoding NAME: for native input, select utf-8, utf-8-bom, utf-16le, utf-16be, windows-1252, or iso-8859-1. Accepted aliases are utf8; utf8-bom and utf-8-sig; utf16le and utf-16-le; utf16be and utf-16-be; windows1252 and cp1252; and iso8859-1, latin1, and latin-1.
• --json: emit one compact deterministic inspection-report-version-1 JSON object plus LF instead of the human report.

Success places the report on stdout and source warnings on stderr. Both modes exclude preserved bytes, content hashes, asset and cue IDs, payload and annotation text, native raw fields, timestamps, free-form diagnostic messages, caller paths, and machine identifiers. Loss is not_evaluated with reason target_format_required until a target-specific operation is requested.

ASS/SSA reports add an optional scripted object of fifteen integer counts. It is omitted from SubRip/WebVTT reports, whose fields and human output retain their established meaning. section_count, record_count, style_count, event_count, and attachment_count count the corresponding retained native collections. format_declaration_count, unknown_record_count, and malformed_record_count count native records by kind. invalid_style_count and invalid_event_count count preserved owners marked invalid; dialogue_event_count and comment_event_count count events by validated type. override_tag_count sums event tag occurrences; karaoke_span_count sums karaoke entries; unsupported_karaoke_span_count counts entries marked unsupported. Drawing-only and non-dialogue native owners remain represented even when they produce no common cue. These counts do not disclose source names, fields, tag parameters, attachment payloads, actors, or text. Existing WebVTT block/body counters are not a scripted record inventory.

The bounded scripted input profile accepts UTF-8 or matching UTF-8 BOM selection across all workflows. Established owning-command error classes remain: encode/validate/inspect report supported but incompatible scripted encodings as runtime refusal (1), while convert's explicit scripted-input preflight reports invocation refusal (2). Unknown encoding tokens remain invocation failures.

cueson inspect testdata/fixtures/webvtt/minimal/source/minimal.vtt
cueson inspect --json testdata/fixtures/webvtt/minimal/source/minimal.vtt

schema

cueson [global options] schema [options]

schema emits the byte-identical canonical schema embedded in the executable.

• --version: print the embedded schema version followed by one LF.
• -o, --output PATH: write schema bytes to a filesystem path instead of stdout.
• -f, --force: replace an approved existing regular filesystem output.

--version cannot be combined with --output or --force; --force requires a filesystem output. Schema or version bytes use stdout unless a file is selected; errors and error-associated short usage use stderr.

cueson schema
cueson schema --version
cueson schema --output quickstart/cueson.schema.json

version

cueson [global options] version

version accepts no local options or operands. Cueson v1.2.0 writes exactly 1.2.0 plus LF to stdout and uses stderr only for errors. Historical v1.1.0, v1.0.0 and v0.0.0 binaries retain their own exact versions.

cueson version

completion

cueson [global options] completion bash|zsh|fish|powershell

completion accepts exactly one case-sensitive selector: bash, zsh, fish, or powershell. It has no local options. Success writes one deterministic UTF-8 LF static definition to stdout and nothing to stderr. Missing, unsupported, or extra selectors exit 2 with empty stdout and an error plus short usage on stderr.

Generated definitions use shell-native registration and never invoke Cueson recursively, execute a subprocess, access a network, inspect subtitle content, infer a shell from environment values, interpret completion candidates as code, or modify a profile.

cueson completion bash
cueson completion powershell

Compatibility and release boundary

The command names, options, aliases, streams and exit-code classes above form the stable v1 CLI compatibility surface. Go packages remain under internal/ and are not public APIs. Published executable and schema identity is 1.2.0, and the immutable v1.2 schema is reviewed, released and independently verified with that identity. GitHub Release publication does not itself serve the public schema endpoint or deploy production state. See the compatibility contract and release process.