arr-cli — read-only media-server CLI

arr-cli is a single Python package that ships five thin CLI executables — jellyfin, radarr, sonarr, maintainerr, seerr — backed by one shared facade (arr_cli.facade) that owns config, HTTP, auth, error mapping, and output formatting. All five binaries can be installed from https://github.com/BottaniCals/arr-cli source.

Every command is an HTTP GET. No write endpoints exist in MVP; the package cannot mutate the media stack.

Two operators:

• Agents / pipelines consume JSON on stdout. Default is a curated summary (sized for chat-agent consumption) for the size-to-summary commands; pass --verbose for full verbatim service JSON.
• Human operators reach for --human / -h for tabular terminal output. Combine with --verbose when you do want the full payload in table form.

Diagnostics always go to stderr, so ... | jq is pipe-clean.

Universal flags

Available on all five CLIs. Run <cli> --help for the per-service synopsis; universal flags are accepted by every subcommand, so position (before vs. after the subcommand) does not matter.

Flag ordering

Universal flags are accepted by every subcommand, so both positions work:

# both equivalent
jellyfin --config ~/.config/arr/local.yaml now
jellyfin now --config ~/.config/arr/local.yaml

# mixed with subcommand-specific positionals
radarr --limit 5 calendar 2026-01-01 2026-01-31
sonarr calendar $(date -I) $(date -I -d '+7 days') --human

<cli> <subcommand> --help lists the universal flags alongside the subcommand's own positionals / options, so an operator can discover them without going to the top-level help.

Per-service commands

jellyfin

radarr

sonarr

maintainerr

Maintainerr ships with no auth. A one-line stderr warning is emitted on every invocation reminding the operator that the endpoint must be reachable only on a trusted / private network — pass --quiet to silence it.

seerr

seerr targets Seer (the unified Overseerr + Jellyseerr fork).

Exit codes (stable contract)

Scripts depending on these codes for control flow:

Argument-parse errors (unknown flag, missing positional, invalid choice) exit 1 (ConfigError) and append a stderr line shaped service=config op=parse message=argument parse error (argparse exit 2). The argparse usage hint stays on stderr above the structured line. Grep stderr for the service=config op=parse prefix to identify parse failures.

Output formats

Three JSON shapes are possible; pick the one your consumer wants.

• Default (no flag) — for the size-to-summary commands listed below: a curated, pipe-clean JSON summary sized for chat-agent consumption. For all other commands: verbatim service JSON unchanged.
• --verbose — full verbatim service JSON for any command (can return hundreds of rows). Use when a downstream pipeline needs the raw payload (server-internal metadata, MediaStreams, ImageBlurHashes, full Capabilities bitmask, etc.).
• --human / -h — tabular view of the same data the command returns by default (summary table for size-to-summary commands, verbatim table for the rest). Pagination via --limit. Use for terminal inspection.
• stderr: diagnostics only. The Maintainerr auth-disabled warning, --debug redacted traces, and service=… op=… error lines all flow here.

Size-to-summary commands (default = summary, opt-in full via --verbose)

jellyfin now, jellyfin resume, jellyfin recent, jellyfin favorites, jellyfin latest, radarr wanted, radarr queue, radarr recent, sonarr wanted, sonarr queue, sonarr recent, seerr requests, seerr search, seerr available, seerr trending, seerr upcoming-movies, seerr upcoming-tv, seerr discover-movies, seerr discover-tv, maintainerr pending.

Everything else (jellyfin item, jellyfin search, jellyfin nextup, radarr calendar, radarr lookup, radarr movie, sonarr calendar, sonarr lookup, sonarr series, seerr request-count, seerr movie, seerr tv, seerr genres, seerr user, maintainerr health, maintainerr storage) is small by design and returns verbatim JSON in both default and --verbose modes.

Stderr error shape (grep-friendly):

service=jellyfin op=now status=401 message=jellyfin: op=now — 401 Unauthorized; check jellyfin.api_key in arr.conf

The service= and op= tokens are stable and safe to parse.

Recipes — intent → command

Lookup vs library-list

radarr lookup / sonarr lookup return candidate records (what the upstream service knows about, whether or not you've added it). The id column on --human output is the disambiguator: populated id means the candidate is already in the library (the monitored field reflects library state); blank id means it's a candidate not yet added (the monitored field is the TVDB/TMDB source default).

For canonical "what's in my library and what's monitored" use sonarr --human series and radarr --human movie — those hit /api/v3/series and /api/v3/movie and reflect actual library state.

Common gotchas

• user_id is required for most Jellyfin commands. The arr.conf jellyfin.user_id field is non-optional for resume, recent, latest, favorites. Missing it → AuthError (exit 2), not ConfigError.
• Calendar dates are ISO-8601 only. radarr calendar next-tuesday → exit 1 (ConfigError) with stderr usage hint. Format strictly as YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS[Z].
• Maintainerr's --quiet matters. Without it, every invocation spams a "no auth, private network only" warning to stderr. Default to maintainerr --quiet <subcommand> for cron / scripted use.
• --debug is loud and slow. Full traceback + redacted request / response pair to stderr. Use for one-shot diagnosis, not in pipelines.
• exit 2 is auth-only. Argument-parse errors exit 1 (ConfigError) and append service=config op=parse message=argument parse error (argparse exit 2) to stderr. Universal flags work before or after the subcommand; both jellyfin now --config X and jellyfin --config X now are valid.
• Search-with-empty-query is not an error — and it's CLI-side. jellyfin search "" (and jellyfin search with no positional) short-circuits to [] without calling /Items. Exit 0, no transport.get fired. Useful when chaining in scripts that may pass empty input.
• Seer endpoints are paginated by default. seerr requests, seerr search, seerr available, seerr trending, seerr upcoming-*, and seerr discover-* all return {page, totalPages, totalResults, results: [...]} envelopes. The size-to-summary renderers unwrap results automatically; pass --verbose to see the full envelope. seerr available requests take=1000 so a single response covers the household queue; queues above 1000 items would need a page-walking follow-up.
• seerr discover-* with no flags sends no defaults on the wire. Pass --sort / --language explicitly when you need them. Trending / upcoming / search / genres already followed the omit-when-default rule and are unaffected.

Smoke-testing without a live service

Quick sanity check that the package is wired (no network):

command -v jellyfin radarr sonarr maintainerr seerr     # all 5 on PATH
python3 -c "import arr_cli"                            # package importable
<cli> --help | head -3                                  # usage renders
<cli> now 2>&1 | grep -q "config file not found" && echo "ok: config gate works"

The last line confirms the canonical config path is being checked before any HTTP call — useful after rebuilding the sandbox image.