---
title: "Jellyfin CLI for AI agents (jf) · Stefan Preu"
description: "jf is an open-source Jellyfin CLI built for AI agents: TOON output, a read-only guard, exact OpenAPI operations, tool schemas and confirmed mutations."
url: https://preu.at/work/jellyfin-cli
updated: 2026-10-19
---

# 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.

- install: `npm install -g jellyfin-cli`
- version: 2026.10.4 · 4 Oct 2026
- commands: `jf`, `jellyfin-cli`, `jf-cli`
- node: ≥ 22.13
- license: MIT
- source: [github.com/unbraind/jellyfin-cli](https://github.com/unbraind/jellyfin-cli)
- works with: [Jellyfin](https://jellyfin.org)

## 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

```sh
# # connect with a server URL and an API key
jf setup --server http://your-server:8096 --api-key YOUR_API_KEY
jf config doctor
jf library list
jf items search "matrix"
```

commands from the project’s README; what they print depends on your server. checked against the README at [b0759c8](https://github.com/unbraind/jellyfin-cli/blob/b0759c8d7a612540114473153eb5c8993424718d/README.md) (npm 2026.10.4) · [npm](https://www.npmjs.com/package/jellyfin-cli)

## 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.

- [Home Assistant CLI](https://preu.at/work/home-assistant-cli): Home Assistant from the command line, built for agents.
- [SearXNG CLI](https://preu.at/work/searxng-cli): web search through your own SearXNG, built for agents.
- [Monica CLI](https://preu.at/work/monica-cli): your personal CRM from the command line, read-only by default.
- [PM CLI](https://preu.at/work/pm-cli): case study. project management is a context problem.

---

[preu.at](https://preu.at/) · Stefan Preu, agentic systems architect, based in austria · [every page for agents](https://preu.at/llms.txt) · this page in a browser: https://preu.at/work/jellyfin-cli