Headless mode

Headless mode

For scheduled or scripted runs, --headless never prompts and --json prints one machine-readable result document regardless of outcome, so a scheduler always has the same shape to parse.

clippy --headless --profile theflood --json

--headless implies -y (auto-confirm), drops color codes, and skips the startup banner — nothing in the output depends on being run in an interactive terminal.

The JSON payload

{
  "status": "ok",
  "exit_code": 0,
  "files": [
    "theflood_2026-07-19_to_2026-07-22_part1.mp4",
    "theflood_2026-07-19_to_2026-07-22_part2.mp4"
  ],
  "broadcaster": "theflood",
  "window": {
    "start": "2026-07-19T00:00:00Z",
    "end": "2026-07-22T00:00:00Z"
  },
  "compilations": 2,
  "credits_file": "output/credits.md",
  "version": "0.8.0"
}

Exit codes

A scheduler can tell "nothing to do" apart from "something broke" without parsing text:

Code	Meaning
0	Built at least one compilation
2	Bad invocation or configuration
3	Ran fine, nothing matched (not a failure — e.g. no new clips this week)
4	Credentials missing or rejected
5	ffmpeg or yt-dlp failed
1	Unexpected failure
130	Interrupted (Ctrl-C or a shutdown signal)

Redirecting the credits file

Every run writes a paste-ready credits.md (see Subsequent runs) to <output-dir>/credits.md by default. For a scripted run that wants it somewhere specific:

clippy --headless --profile theflood --json --credits-file /path/to/credits.md

The path is also in the --json payload's credits_file field, so a script never has to guess it.

Scheduling examples

cron (Linux/macOS), every Monday at 6am:

0 6 * * 1  clippy --headless --profile theflood --json --credits-file output/credits.md >> /var/log/clippy.log 2>&1

Windows Task Scheduler — set the action to run clippy.exe with arguments --headless --profile theflood --json, working directory set to wherever clippy.yaml/.env live.

Next

If a scheduled run isn't behaving the way you expect, see Troubleshooting.