01 / Start
Run without a global install
Pin the package version for stable agent runs. npx downloads the package and starts the selected command.
npx -y chrona-cli@0.1.0 --json doctor
npx -y chrona-cli@0.1.0 --json probe ./video.mp4
npx -y chrona-cli@0.1.0 --json extract ./video.mp4 --output frames.zip- • The npm package installs pinned FFmpeg 6.1.1 and FFprobe binaries for supported systems.
- • Chrona uses a command option before an environment variable.
- • Set `CHRONA_FFMPEG` or `CHRONA_FFPROBE` to override an installed binary.
- • Next, Chrona uses the installed binary before a compatible binary on `PATH`.
- • If npm skips install scripts, Chrona uses compatible binaries on `PATH`.
- • If Chrona cannot run a binary, reinstall the package or pass an explicit path.
- • The binary packages include their GPL-3.0-or-later license files.
- • If you redistribute the binaries, read those license files.
02 / Model
Choose the local surface
Use the CLI for scripts, shells, and direct process control.
Use MCP for tool discovery and typed calls from an agent host.
Use plan files to move edits between the browser, CLI, and MCP.
Use the website only to share a finished ZIP for 24 hours.
Chrona keeps source media on the local machine. A media API moves source media across a network and breaks that rule.
The MCP server adds tool discovery. It calls the same local service as the CLI.
03 / Coverage
Feature parity
Every browser outcome has a CLI command or option.
| Browser outcome | Agent action |
|---|---|
| Open a local video | Pass a local path to `probe`, `plan`, `estimate`, or `extract`. |
| Read video details | Run `probe`. |
| Detect solid borders | Use the default `--crop auto` mode. |
| Trim the start and end | Use `--start` and `--end`. |
| Remove many sections | Repeat `--cut START..END`. |
| Keep original timing | Use `--fps original`. |
| Choose a fixed rate | Use a decimal or rational value with `--fps`. |
| Estimate the ZIP size | Run `estimate`. |
| Export lossless PNG frames | Use `--quality 100`. |
| Create a smaller ZIP | Use `--quality 50` through `--quality 99`. |
| Inspect frame previews | Run `frame` for any exported frame. |
| Download the ZIP | Run `extract` with a ZIP output path. |
| Create a 24-hour link | Run `share` on the finished ZIP. |
| Open a shared ZIP | Run `download` on the share link. |
| Move edit settings | Import or export a version 2 plan. |
| Cancel active work | Cancel the CLI process or the MCP tool call. |
04 / Reference
Commands
doctor
Check FFmpeg and FFprobe.npx -y chrona-cli@0.1.0 --json doctor- • Exit code 3 means that Chrona cannot run a native binary.
probe
Read video details, exact frame times, and the detected border crop.npx -y chrona-cli@0.1.0 --json probe ./video.mp4- • Add `--fast` to skip the exact frame timing scan.
- • Add `--no-auto-crop` to skip border detection.
plan
Create a portable versioned plan without writing frames.npx -y chrona-cli@0.1.0 --json plan ./video.mp4 --start 00:02 --end 00:12 --cut 00:05..00:07 --fps 30000/1001 --quality 80 --write edit.chrona.json- • The default crop mode is `auto`.
- • Use `--crop none` to keep the full displayed frame.
- • Use `--crop LEFT:TOP:WIDTH:HEIGHT` for an exact crop.
estimate
Estimate frame count and output size from three PNG samples.npx -y chrona-cli@0.1.0 --json estimate ./video.mp4 --plan edit.chrona.json- • The estimate uses the plan crop, rate, ranges, and quality.
extract
Write continuous, one-based PNG frames and a manifest.npx -y chrona-cli@0.1.0 --json --progress json extract ./video.mp4 --plan edit.chrona.json --output frames.zip- • Use `--dry-run` to inspect the plan and FFmpeg filter.
- • A dry run never creates output files.
- • Use `--overwrite` to replace an existing ZIP or directory.
validate
Validate frame names, manifest data, and PNG dimensions.npx -y chrona-cli@0.1.0 --json validate ./frames.zip- • The command accepts a ZIP or an extracted directory.
frame
Copy one full-size PNG from a ZIP or directory.npx -y chrona-cli@0.1.0 --json frame ./frames.zip 42 --write frame-42.png- • Use this command for visual inspection or vision model input.
share
Upload a finished ZIP and create a 24-hour link.npx -y chrona-cli@0.1.0 --json share ./frames.zip- • This command validates the ZIP before upload.
- • Use `--app-url` or `CHRONA_APP_URL` to target another Chrona deployment.
- • The command never uploads the source video.
download
Download and validate a shared ZIP.npx -y chrona-cli@0.1.0 --json download https://chrona.fyi/artifacts/TOKEN --output frames.zip- • Use `--overwrite` to replace an existing ZIP.
schema
Print the plan or manifest JSON Schema.npx -y chrona-cli@0.1.0 --json schema plan- • Use `schema manifest` for the extraction manifest.
mcp
Run the MCP server over standard input and output.npx -y chrona-cli@0.1.0 mcp- • The server exposes each CLI outcome as a typed tool.
05 / Inputs
Options
Global options
- --json
- Write one JSON result to standard output.
- --progress tty|json|none
- Write progress to standard error.
- --quiet
- Hide the human result.
Native tools
- --ffmpeg-path PATH
- Override the installed FFmpeg executable.
- --ffprobe-path PATH
- Override the installed FFprobe executable.
Edit and output options
- --start TIME
- Set the retained start.
- --end TIME
- Set the retained end.
- --cut START..END
- Remove one half-open range. Repeat this option for more cuts.
- --fps MODE
- Use original timing, the detected rate, a decimal rate, or a rational rate.
- --crop MODE
- Use auto, none, or LEFT:TOP:WIDTH:HEIGHT.
- --quality 50..100
- Set the PNG detail and output dimensions.
- --archive zip|directory
- Write a ZIP or a directory.
- --output PATH
- Set the output path.
Extraction options
- --plan PATH
- Read a versioned plan. Use a source path with browser plans.
- --dry-run
- Show the work without creating output.
- --overwrite
- Replace an existing output.
- --png-depth 8|16|auto
- Set the PNG channel depth.
- --compression 0..9
- Set lossless PNG compression effort.
- --keep-temp
- Keep temporary frames for debugging.
Sharing
- --app-url URL
- Use another Chrona website for sharing.
06 / Automation
JSON contract
- Place `--json` before or after the command.
- A successful command writes one JSON value to standard output.
- A failed command writes one JSON error to standard output.
- Use `--progress json` for JSON Lines on standard error.
- Chrona never prompts in JSON mode.
- Paths in JSON results are absolute paths.
07 / Interchange
Portable plans
- • Plan schema version 2 stores retained source ranges, rate, crop, quality, and archive type.
- • Browser plans include source file size and duration.
- • Chrona rejects a plan after the source size or duration changes.
- • CLI plans can include local input and output paths.
- • Browser exports omit local paths.
- • Run `schema plan` to get the complete JSON Schema.
npx -y chrona-cli@0.1.0 --json plan ./video.mp4 --write edit.chrona.json
npx -y chrona-cli@0.1.0 --json extract ./video.mp4 --plan edit.chrona.json08 / Tool protocol
MCP server
Add this server to an MCP host. The host starts a pinned npx process.
{
"mcpServers": {
"chrona": {
"command": "npx",
"args": ["-y", "chrona-cli@0.1.0", "mcp"]
}
}
}09 / Recovery
Exit codes
One release, two local interfaces
- • Pin the package version in scripts and MCP settings.
- • The website and npm package come from the same repository release.
- • The npm package includes the CLI, MCP server, schemas, native tools, and shared core rules.
- • The browser app does not require the npm package.