Jellyfin Agent CLI

jellyfin-agent-cli

A Rust-based CLI that talks to Jellyfin media servers. The user is either using the CLI to interact with a Jellyfin instance, or developing the CLI itself. Both cases are covered below.

Description

jellyfin-agent-cli is a terminal-first Jellyfin client that covers everyday browsing and playback, administrative commands, and automation-oriented workflows. The CLI returns structured command results by default (YAML), provides a dedicated structured help surface, and includes E2E and REPL support.

Prerequisites

• A reachable Jellyfin server for server-backed commands
• Valid Jellyfin credentials for authenticated commands
• Network access to the configured Jellyfin instance

Invocation

The binary name is jellyfin-agent-cli. During development use cargo run -- as a prefix.

# Installed binary
jellyfin-agent-cli search "The Matrix"

# Development
cargo run -- search "The Matrix"

# Structured output (all commands support --output)
cargo run -- search "The Matrix" --output json

# Human-readable help
cargo run -- --help
cargo run -- items --help

# Structured help (machine-parseable)
cargo run -- help --format json
cargo run -- help items list --format yaml

Always prefer cargo run -- unless the user explicitly says they're using the installed binary.

Most commands need an authenticated session. The login command saves credentials under a profile name:

cargo run -- login --server http://192.168.1.100:8096 --username admin --password secret --name home

After login, commands use the default profile. Switch profiles with context use <name> or override per-invocation with -P <name>.

Input

Global Options

Commands

The CLI has leaf commands and grouped commands with subcommands. Key groups:

Media browsing: search <query>, latest, continue, libraries list, items list, items get, genres, studios, actors, channels list, remote-search <query>

Playback: play <item_id>, pause, resume, playback info, playback seek, playback stop, playback queue

Admin: users list|get|create|delete, sessions, activity-log, system restart|shutdown, scheduled-tasks list|start|stop, devices list, plugins list|uninstall

Collections: playlists list|get|create|add|remove|delete, items favorite|unfavorite|favorites|rate

Notifications: notifications list|mark-read|mark-all-read

Config & profiles: config show|list-servers|set-default|remove-server, context show|use, info, stats

Testing: e2e setup|start|stop|status|logs|reset|media|config

Interactive: repl (tab-completed interactive shell), help (structured help in yaml/json/toml)

When constructing commands, use --help on any group to discover subcommands.

Help Contract

• --help renders human-readable man-like help and exits 0
• Bare top-level or non-leaf invocation renders human-readable help and exits 0
• help --format yaml|json|toml [COMMAND_PATH...] renders structured help
• Missing required leaf input returns a structured error envelope in the selected --output format

Runtime Directories

Log Location

Logs are stored at ~/Library/Application Support/jellyfin-cli/e2e/data/log on macOS. Override via --data-dir or JELLYFIN_DATA_DIR environment variable.

Active Context

• context show reveals the persisted context
• context use <NAME> persists a new active context
• --profile <NAME> overrides for one invocation only
• Command results surface active_context metadata when context resolution matters

Output

Every command supports --output (or -o) with values: yaml (default), json, toml, table, ndjson.

For scripting and automation, --output json or --output ndjson is usually best. For human consumption, --output table or the default YAML works well.

cargo run -- search "The Matrix"
cargo run -- search "The Matrix" --output json
cargo run -- e2e status --output toml

Human-readable help is always requested with --help and never shares the structured result formatter. Structured help is available only through the help command:

cargo run -- help --format yaml
cargo run -- help context --format json

REPL Mode

Start an interactive shell with repl:

cargo run -- repl

Within REPL: help shows plain-text help, exit/quit ends the session. Tab completion and command history (persisted between sessions) are available. Default REPL output is human-readable; use --output json|yaml|toml for structured output.

Errors

All command failures use a structured error envelope with machine-readable code and human-readable message.

command: jellyfin-agent-cli items get
status: error
summary: Command failed.
errors:
  - code: input_invalid
    message: "Invalid arguments: the following required arguments were not provided: <ITEM_ID>"

Typical exit codes: 0 success, 10 authentication error, 20 network error, 30 API error, 40 input validation, 50 internal error.

Examples

# Human-readable help
cargo run -- --help

# Structured help
cargo run -- help context --format yaml

# Persist a context
cargo run -- context use home

# Override the active context for one invocation
cargo run -- info --profile staging --output json

# Update the default profile
cargo run -- config set-default --name home

# Start the E2E environment
cargo run -- e2e setup
cargo run -- e2e start --wait

# Search across all libraries
cargo run -- search "The Matrix"

# Get JSON output for scripting
cargo run -- search "The Matrix" --output json