CLI

The Closed Caption Converter CLI brings the full power of the conversion engine to your command line. It runs entirely on your local machine as a single self-contained binary with no external dependencies — no runtime installations, no package managers, no library conflicts. Deploy it once and it works. When you need to upgrade, you replace a single file.

The CLI is available for macOS, Windows, and Linux, and is designed for environments where sending files to a cloud API is not possible or desirable: air-gapped networks, serverless deployments, on-premise infrastructure, or any facility that requires caption processing to happen within the security perimeter.

Installation

Download the CLI binary for your platform from the Closed Caption Converter website or from the Downloads section of your dashboard.

The CLI is distributed as a single executable file:

Platform	Binary Name
macOS (Apple Silicon)	cc-converter-macos-arm64
macOS (Intel)	cc-converter-macos-x64
Windows	cc-converter-win.exe
Linux	cc-converter-linux

On macOS and Linux, make the binary executable after downloading:

chmod +x cc-converter-macos-arm64

You may optionally move it to a directory on your PATH (for example /usr/local/bin/) to run it from anywhere:

mv cc-converter-macos-arm64 /usr/local/bin/cc-converter

On Windows, place the .exe in a directory on your PATH or reference it by full path in your scripts.

Activation

The CLI requires a valid license file to run. Place the license file in the same directory as the binary or specify its path using the --license flag. Contact sales and support to obtain a license key.

Running Your First Conversion

The CLI accepts a Job Description JSON file as its primary input. This is the same JSON format used by the API, making it easy to develop and test job configurations in the web application and then run them locally with the CLI.

To convert a file, pass the source file and the job configuration:

cc-converter \
  --source input.srt \
  --config job.json \
  --output output.stl

Where job.json contains a standard Job Description:

{
  "job_type": "convert",
  "source_profile": "SubRip Video Subtitle Script",
  "target_profile": "EBU STL",
  "default_frameRate": 25,
  "encoding_options": [
    { "name": "Language Code", "selected": "English" },
    { "name": "Country of Origin", "selected": "United Kingdom" }
  ]
}

The --output flag specifies the path where the converted file will be written. If omitted, the output file is written to the same directory as the source file with the correct target extension.

Using Presets

You can use a stored Job Preset from the dashboard instead of a full Job Description file. Specify the preset ID in the config JSON and ensure the CLI has network access to resolve it:

{
  "preset_id": "your-preset-id-here"
}

Alternatively, for fully offline workflows, provide the complete Job Description JSON locally. The CLI works entirely offline when a full configuration is provided — no network access is required.

Batch Processing

The CLI supports batch processing of multiple files using a glob pattern or a newline-separated list of source paths:

cc-converter \
  --source "/captions/*.srt" \
  --config job.json \
  --output-dir /converted/

Each file in the batch is processed independently using the same job configuration. Output files are written to the --output-dir directory with the same base filename and the target profile's extension.

Common Use Cases

On-Premise Broadcast Automation

Many broadcast facilities run automation systems (such as Ross Overdrive, Imagine Versio, or custom scripting) that need to process caption files as part of a playout workflow. The CLI integrates into these automation chains as a command-line step, requiring no network connectivity to the Closed Caption Converter API.

AWS Lambda and Serverless Functions

Because the CLI is a single binary with zero dependencies, it is well suited for deployment inside containerised or serverless functions. Drop the binary into your Lambda deployment package or Docker image, reference it from your function handler, and invoke it with a job configuration assembled at runtime.

Air-Gapped Environments

Government agencies, secure post facilities, and content distributors that process confidential or unreleased material often require that files never leave a controlled network. The CLI processes all files locally with no data transmission — ideal for these environments.

Scripted Format Conversion Pipelines

Any scripting environment that can invoke a subprocess can wrap the CLI. Python, bash, PowerShell, Node.js, and Ruby scripts can all call the CLI, check the exit code, and process the output file as part of a larger automated workflow.

Exit Codes

Code	Meaning
0	Job completed successfully.
1	Job failed due to a processing error. Error details are written to stderr.
2	Invalid arguments or configuration file path not found.
3	License file invalid or not found.

Getting Help

For questions about CLI deployment, licensing, or integration support, contact the Closed Caption Converter team at closedcaptionconverter.com/contact.html.