> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Commands

> Every coreav command, and what inputs, outputs, exit statuses and errors they share.

The `coreav` command has one subcommand per job. Each page here shows the command's `--help` text, as the command prints it.

## Commands

| Command | What it does |
| - | - |
| [`probe`](/docs/commands/probe) | Describes an MP4, MOV, Matroska, WebM or MPEG-TS file as JSON. |
| [`check`](/docs/commands/check) | Checks a file against an upload policy and prints the verdict. |
| [`chapters`](/docs/commands/chapters) | Prints the QuickTime chapter list of an MP4 or MOV file. |
| [`clip`](/docs/commands/clip) | Cuts a keyframe-aligned clip of an MP4 or MOV file. |
| [`split`](/docs/commands/split) | Splits an MP4 or MOV file at keyframes into MP4 segments. |
| [`join`](/docs/commands/join) | Joins MP4 or MOV files that share a codec configuration. |
| [`remux`](/docs/commands/remux) | Rewrites MP4, MOV, Matroska or WebM as MP4 with the movie header first. |
| [`sanitize`](/docs/commands/sanitize) | Rewrites an MP4 or MOV file without its metadata. |
| [`extract-audio`](/docs/commands/extract-audio) | Copies the AAC track of an MP4 or MOV file into M4A. |
| [`extract-subtitles`](/docs/commands/extract-subtitles) | Writes the text subtitles of an MP4 or MOV file as WebVTT. |
| [`decode-audio`](/docs/commands/decode-audio) | Decodes a FLAC or MP3 track to WAV. |
| [`hls`](/docs/commands/hls) | Serves an MP4 or MOV file as HLS. |
| [`ffprobe`](/docs/commands/ffprobe) | Experimental. Runs an `ffprobe` command line. |
| [`ffmpeg`](/docs/commands/ffmpeg) | Runs an `ffmpeg -c copy` command line. |
| [`thumbnail`](/docs/commands/thumbnail) | Writes an image of the frame at a time. Builds with a decoder backend only. |
| [`transcode`](/docs/commands/transcode) | Re-encodes the video to H.264 in MP4. Builds with a decoder backend only. |

Only `decode-audio`, `thumbnail` and `transcode` decode anything, and only `transcode` encodes. The other commands copy the coded data as it is.

## Inputs

An input is a local file. In native builds, the commands that read one media file (`probe`, `check`, `clip`, `split`, `extract-audio`, `remux`, `sanitize`, `extract-subtitles` and `chapters`) also read an `https://` URL, by byte ranges, never downloading the whole file ([remote media](https://github.com/coreav-dev/coreav/blob/main/docs/design/remote.md)).

## Outputs

* A command that writes a file writes it under a temporary name and renames it into place, so a failed run leaves no partial output.
* A command refuses to overwrite an existing file unless you pass `--force`, and never writes over its input.
* Most commands take `-` as the output, for standard output. The JSON summary then goes to standard error.
* Each JSON document names its schema, such as `coreav.probe/1`. The schemas are in [`docs/schema`](https://github.com/coreav-dev/coreav/tree/main/docs/schema).

## Exit statuses

| Status | Meaning |
| - | - |
| 0 | Success. For `check`, the file is accepted. |
| 1 | The file was rejected: unsupported, damaged or not allowed. For `check`, the verdict is on standard output. |
| 2 | Usage error: bad arguments or an invalid policy. |
| 3 | I/O error: a missing file, an unreadable URL or an unwritable output. |
| 4 | Refused: `coreav ffprobe` or `coreav ffmpeg` refused a command line it does not implement, or strict-safe mode refused what would run an `ffmpeg` program ([strict-safe mode](/docs/strict-safe.md)). |
| 141 | Standard output was closed by its reader, as in `coreav probe input.mp4 \| head`. |

## Errors

On exit status 1 and 3, standard error holds one JSON object (`coreav.error/1`), except a rejection by `check`, whose verdict is on standard output:

```json theme={null}
{"kind":"unsupported_container","limit":null,"message":"not an ISO base media or QuickTime file","offset":null,"schema":"coreav.error/1"}
```

`kind` is stable and meant for programs. `message` is for people. Usage errors are plain text that starts with `error:`.

## Global options

```text theme={null}
The coreav command: memory-safe probing of MP4/MOV, Matroska, WebM and MPEG transport stream files, local or at an HTTP(S) URL; clipping, splitting, joining, sanitizing, audio, subtitle and chapter extraction and HLS packaging of MP4/MOV files; remuxing of all of them to MP4; decoding of their audio to WAV; and upload policy checks

Usage: coreav [OPTIONS] <COMMAND>

Commands:
  probe              Describe an MP4, MOV, Matroska or WebM file as JSON
  clip               Cut a keyframe-aligned clip of an MP4/MOV file to MP4, without re-encoding
  split              Split an MP4/MOV file at keyframes into MP4 segments, without re-encoding. Together the segments hold every packet of the kept streams exactly once
  check              Check an MP4, MOV, Matroska or WebM file against an upload policy and print the verdict as JSON
  extract-audio      Copy the AAC audio track of an MP4/MOV file into an M4A file, without re-encoding
  decode-audio       Decode an audio track of an MP4/MOV, Matroska or WebM file to a WAV file (FLAC, MP3)
  remux              Rewrite an MP4/MOV, Matroska or WebM file as MP4 with the movie header first (faststart), without re-encoding
  extract-subtitles  Write the text subtitles (mov_text: 3GPP timed text or QuickTime text) of an MP4/MOV file as WebVTT
  chapters           Print the QuickTime chapter list of an MP4/MOV file as JSON
  sanitize           Rewrite an MP4/MOV file as MP4 without its metadata (location, device, dates), keeping only allowlisted boxes, without re-encoding
  join               Join MP4/MOV files that share a codec configuration into one MP4, without re-encoding
  hls                Serve an MP4/MOV file as HLS with fragmented MP4 (CMAF) segments, without re-encoding
  ffprobe            Experimental. Runs an ffprobe command line: ffprobe's own options, a supported subset. With --strict-safe (COREAV_STRICT_SAFE=1), for untrusted input, anything else is refused with exit status 4; without it, anything else runs the ffprobe program on PATH, FFmpeg's C code (docs/design/compat-cli.md). Values can differ from ffprobe's for MP4/MOV and MPEG-TS; Matroska/WebM agree on 98% or more of files for 99 of 101 keys (docs/measurements/compat-ffprobe.md). `coreav` run as `ffprobe` does the same
  ffmpeg             Runs an ffmpeg stream-copy command line (-c copy) with CoreAV's own writers: remuxing to MP4, clipping, segmenting and audio extraction to M4A, with ffmpeg's stream selection. With --strict-safe (COREAV_STRICT_SAFE=1), for untrusted input, anything else is refused with exit status 4; without it, anything else runs the ffmpeg program on PATH, FFmpeg's C code (docs/design/compat-cli.md). `coreav` run as `ffmpeg` does the same
  help               Print this message or the help of the given subcommand(s)

Options:
      --strict-safe  For services that read untrusted input: CoreAV never runs an ffmpeg or ffprobe program, which is FFmpeg's C code, as COREAV_STRICT_SAFE=1 does. `coreav ffprobe` and `coreav ffmpeg` refuse a command that is not native (exit status 4) instead of running it with FFmpeg, and a thumbnail or transcode never decodes or encodes with FFmpeg: a video only FFmpeg would decode, and an encode without an x264 program, are refused (exit status 4)
  -h, --help         Print help
  -V, --version      Print version
```

## How this reference stays in agreement with the help

The help text on each page is generated from the command's `--help`. A test, `crates/coreav-cli/tests/docs_site.rs`, runs every command's `--help` and fails when a page's text differs, or when a command has no page. CI runs it in the default build and in a build with a decoder backend.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.