ffmpeg CLI

CuratedAudited 2026-10-28 by anc 0.7.0Markdown · JSON
60pass rate

2/8 principles met

Record, convert, and stream audio and video

$ anc audit ffmpeg --json

workhorse C FFmpeg/FFmpeg
MUST 19 / 28SHOULD 14 / 223 failing11 warningsaudited 2026-10-28 · anc 0.7.0

Eight principles, scored

Behavioral and source checks. Every non-pass row carries a copy-paste remediation prompt.

  1. P1
    Non-Interactive by Default

    46 flag(s) found in --help but no `[env: NAME]` bindings advertised · no default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).

    Remediation · P1
    Make ffmpeg satisfy P1 (Non-Interactive by Default) from the agent-native CLI standard. Address:
    - Flags advertise env-var bindings in --help (46 flag(s) found in --help but no `[env: NAME]` bindings advertised)
    - `--help` advertises default values for flags (no default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).)
    - Rich-TUI affordance for TTY contexts (no rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.)
    Requirements: https://anc.dev/p1
    warn
  2. P2
    Structured, Parseable Output

    no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum. · no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.

    Remediation · P2
    Make ffmpeg satisfy P2 (Structured, Parseable Output) from the agent-native CLI standard. Address:
    - --json / --jsonl short aliases for --output (no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.)
    - `--raw` flag for pipe-safe unformatted output (no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.)
    - Bad invocation exits with structured usage-error code (2) (bad invocation exited with code 8. The 0/1/2/77/78 convention reserves code 2 for usage errors; using a different non-zero code (often 1) blurs the distinction between usage errors and general failure.)
    Requirements: https://anc.dev/p2
    warn
  3. P3
    Progressive Help Discovery

    `--version` exited with code 8 · `--version` exited with code 8

    Remediation · P3
    Make ffmpeg satisfy P3 (Progressive Help Discovery) from the agent-native CLI standard. Address:
    - Version flag works (`--version` plus short alias) (`--version` exited with code 8)
    - Version flag works (`--version` plus short alias) (`--version` exited with code 8)
    - `examples` subcommand or `--examples` flag for curated usage patterns (no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.)
    - Short `-h` summary differs from `--help` long form (`-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.)
    - Help text pairs human and `--output json` example invocations (no paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.)
    Requirements: https://anc.dev/p3
    fail
  4. P4
    Fail-Fast, Actionable Errors

    stderr lacks a hint phrase. Looked for one of: try , use , expected , did you mean, see , run , for more, tip:, help:, hint:, suggestion:, available . Error messages must name what to do next, not just the symptom.

    Remediation · P4
    Make ffmpeg satisfy P4 (Fail-Fast, Actionable Errors) from the agent-native CLI standard. Address:
    - Error messages include a hint or remediation phrase (stderr lacks a hint phrase. Looked for one of: try , use , expected , did you mean, see , run , for more, tip:, help:, hint:, suggestion:, available . Error messages must name what to do next, not just the symptom.)
    Requirements: https://anc.dev/p4
    fail
  5. P5pass
  6. P6
    Composable, Predictable Command Structure

    no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.

    Remediation · P6
    Make ffmpeg satisfy P6 (Composable, Predictable Command Structure) from the agent-native CLI standard. Address:
    - `--color` flag for explicit color control (no `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.)
    Requirements: https://anc.dev/p6
    warn
  7. P7
    Bounded, High-Signal Responses

    no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.

    Remediation · P7
    Make ffmpeg satisfy P7 (Bounded, High-Signal Responses) from the agent-native CLI standard. Address:
    - Quiet mode available (no option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.)
    Requirements: https://anc.dev/p7
    warn
  8. P8pass

All Audits

P1: Non-Interactive by Default

PASSNon-interactive by default
SKIPNon-interactive gate flag advertised in --helptarget satisfies P1 via alternative gate (help-on-bare or stdin-primary)
WARNFlags advertise env-var bindings in --help46 flag(s) found in --help but no `[env: NAME]` bindings advertised
PASSSecret-bearing flags expose stdin or *-file companion
WARN`--help` advertises default values for flagsno default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).
WARNRich-TUI affordance for TTY contextsno rich-TUI affordance detected (no `--tui`/`--interactive`/`--ui` flag, no spinner/progress/tui mention in --help). MAY-tier — rich TUI in TTY contexts is a nice-to-have, not required.

P2: Structured, Parseable Output

OPT-OUTStructured output supportno option definition in --help declares --output, --format, --output-format, --json or --jsonl, the flags this requirement accepts; a flag named only in a usage line does not count.
N/AStructured-output CLI exposes its schema at runtimeantecedent `p2-json-output` is opt_out: no option definition in --help declares --output, --format, --output-format, --json or --jsonl, the flags this requirement accepts; a flag named only in a usage line does not count.
WARN--json / --jsonl short aliases for --outputno --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.
WARN`--raw` flag for pipe-safe unformatted outputno `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.
SKIP`--output` advertises additional formats beyond text/jsonno `--output` or `--format` flag advertised; vacuous skip for MAY-tier extra formats.
WARNBad invocation exits with structured usage-error code (2)bad invocation exited with code 8. The 0/1/2/77/78 convention reserves code 2 for usage errors; using a different non-zero code (often 1) blurs the distinction between usage errors and general failure.
SKIPErrors emit JSON envelope with discriminant + type id + message roles under `--output json`no option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); MUST applies only to CLIs that opt into the JSON contract.
SKIPJSON success and error envelopes share their non-payload key setno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); envelope-consistency only applies to CLIs that opt into the JSON contract.

P3: Progressive Help Discovery

PASSHelp flag produces useful output
FAILVersion flag works (`--version` plus short alias)`--version` exited with code 8
FAILVersion flag works (`--version` plus short alias)`--version` exited with code 8
WARN`examples` subcommand or `--examples` flag for curated usage patternsno `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.
WARNShort `-h` summary differs from `--help` long form`-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.
SKIPEach subcommand that takes arguments ships an invocation example in its `--help`no command block found in --help output, so no subcommands were parsed; the MUST applies conditionally to CLIs that use subcommands.
WARNHelp text pairs human and `--output json` example invocationsno paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.
N/ACommand-list entries name the command without repeating the binary nameno command block found in --help output, so no subcommands were parsed; the SHOULD applies to CLIs that list subcommands.

P4: Fail-Fast, Actionable Errors

PASSRejects invalid arguments
FAILError messages include a hint or remediation phrasestderr lacks a hint phrase. Looked for one of: try , use , expected , did you mean, see , run , for more, tip:, help:, hint:, suggestion:, available . Error messages must name what to do next, not just the symptom.
SKIP`--output json` produces JSON-formatted errorsno option definition in --help declares a JSON mode (an output flag whose definition names json, or a --json or --jsonl alias); SHOULD applies only to CLIs that opt into the JSON contract.

P5: Safe Retries & Mutation Boundaries

SKIPDestructive subcommands require `--force` or `--yes`no destructive subcommands detected; MUST applies conditionally to CLIs with destructive operations.
SKIPRead and write surfaces are both visible in subcommand listno recognizable read or write subcommand verbs; the read/write distinction is unobservable from the help surface alone.

P6: Composable, Predictable Command Structure

PASSHandles SIGPIPE gracefully
SKIPPager-using CLI ships --no-pager escape hatchno pager signal ($PAGER, --pager, pager, or less/more named as a program) in --help
PASSRespects NO_COLOR
SKIPSubcommand verbs follow community-standard namesno command block found in --help output, so no subcommands were parsed
WARN`--color` flag for explicit color controlno `--color` flag advertised. MAY-tier — `auto|always|never` lets agents and pipelines override the TTY-based default.
SKIPInput-accepting commands read from stdin when no file is givenno input-accepting subcommand detected (process/parse/convert/transform/analyze/validate/format/lint/audit); vacuous skip for the conditional SHOULD.
SKIPSubcommand naming follows a consistent verb/noun conventionfewer than 2 user-defined subcommands; vacuous skip for the conditional SHOULD.
PASSOperations are subcommands, not verb-shaped flags

P7: Bounded, High-Signal Responses

WARNQuiet mode availableno option definition in --help declares --quiet or -q; a flag named only in a usage line does not count.
PASS`--verbose` flag for diagnostic escalation
SKIP`--limit` / `--max-results` flag for list operationsno list-style subcommand detected (list/ls/search/query/find, or a show/get whose summary describes several results); vacuous skip for the list-only SHOULD.
SKIPCursor-based pagination flags for list traversalno list-style subcommand detected (list/ls/search/query/find, or a show/get whose summary describes several results); vacuous skip for the list-only MAY.
SKIP`--timeout` flag for long-running operationsno long-running subcommand detected (serve/daemon/watch/tail/monitor/follow/run/start/stream); vacuous skip for the conditional SHOULD.
PASSHelp text advertises TTY-aware verbosity behavior

P8: Discoverable Through Agent Skill Bundles

N/ASkill bundle has install path (`tool skill install [<host>]`)no skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill install --all` for multi-runtime installno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand
N/A`skill update` / `skill upgrade` for bundle refreshno skill bundle (AGENTS.md or SKILL.md) found and --help declares no `skill` subcommand

Details

Version scored
9.0.2
Audit date
2026-10-28 15:52:52 UTC
Duration
81ms
Platform
linux/x86_64
Mode
command
Anc build
0.7.0
Install
brew install ffmpeg

Embed the badge

The badge floor is 70%; this scorecard is at 60% (10 points below). Once the score clears the floor, the embed snippet will appear here. The top issues above are the place to start.

Reproduce this scorecard for ffmpeg locally and inspect the failing audits:

anc audit --command ffmpeg --output json

Install anc first if you don't have it. Add --output json to get the same JSON shape committed under scorecards/.