preu.at / work / jellyfin-cli

Jellyfin CLI

a Jellyfin server from the command line: typed commands for the everyday parts, and checked access to every API operation for the rest.

what it’s for

jf covers libraries, items, sessions and playback, users, collections, playlists, live TV, plugins, scheduled tasks, devices and backups. every result is a stable envelope with a type and its data, in official TOON by default, or JSON, YAML, markdown and tables.

where no typed command exists yet, the api commands reach every operation in the server’s OpenAPI document, with rules: reading and writing are different commands, undeclared parameters are rejected, and responses have a size limit.

what it covers

  • libraries
  • items
  • sessions and playback
  • users
  • collections
  • playlists
  • live TV
  • plugins
  • scheduled tasks
  • devices
  • backups
  • subtitles
  • SyncPlay
  • WebSocket events

built for agents

walls around the effects

a media server is somebody’s evening. agents can read freely; changes have to be asked for on purpose.

  • a guard before the network

    read-only mode blocks mutating commands with a structured error, and stops raw API writes before any request is sent. reads keep working.

    export JELLYFIN_READ_ONLY=1

  • inspect before calling

    returns an operation’s exact contract (parameters, body, responses and an argv template) without side effects.

    jf api inspect GetUserById

  • check a plan, then run it

    a batch of reads is validated in full before the first request, then runs in order with per-response byte limits.

    jf api batch --file reads.json --dry-run

  • writes are a different verb

    mutations go through their own command and need --confirm.

    jf api mutate <operationId> --confirm

  • tools for function calling

    exports commands as tool schemas with read-only metadata, ready for a model’s function-calling interface.

    jf schema tools

  • see what it would send

    prints the request a command maps to on stderr, with credentials redacted.

    jf --explain system info

a first run

● commands from the READMEjf 2026.10.4
# connect with a server URL and an API keyjf setup --server http://your-server:8096 --api-key YOUR_API_KEYjf config doctorjf library listjf items search "matrix"
commands from the project’s README; what they print depends on your server.

checked against the README at b0759c8 (npm 2026.10.4) · npm

same rules, four services

each service CLI pairs compact, structured output with discovery an agent can read and writes that have to be asked for.