Jellyfin API Client CLI

A powerful command-line interface for interacting with Jellyfin media servers. This tool provides easy access to your Jellyfin server's API functionality through an interactive menu or command-line arguments.

Features

• 🔐 Flexible Authentication - Support for API tokens, username/password, and automatic token validation
• 📁 Library Management - List, browse, and export library content
• 🔍 Content Search - Search across all your media libraries
• 📊 Server Information - View server status, active sessions, and user details
• 📤 Export Functionality - Export library content in JSON, CSV, or text formats
• ⚙️ Configuration Management - Load settings from config files
• 🐛 Debug Mode - Detailed logging for troubleshooting
• 🎨 Colored Output - Easy-to-read colored terminal output

Installation

Prerequisites

• Bash (version 4.0 or higher)
• curl - For making HTTP requests
• jq (optional but recommended) - For better JSON parsing

Install jq on your system:

# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq

# CentOS/RHEL
sudo yum install jq

Download

# Clone the repository
git clone https://github.com/AlessandroPerazzetta/jellyfin-api-client.git
cd jellyfin-api-client

# Make the script executable
chmod +x cli.sh

Quick Start

1. Interactive Menu Mode

./cli.sh -m

2. Using Configuration File

Create a config file with your Jellyfin server details:

# config file
URL=http://192.168.1.34:8096
TOKEN=your_api_token_here
USERNAME=your_username
PASSWORD=your_password

Then run:

./cli.sh -c config -m

3. With Debug Output

./cli.sh -c config -m -d

Usage

Command Line Options

Usage: ./cli.sh [options]

Options:
  -m, --menu       Show interactive menu
  -c, --config     Load configuration from file
  -d, --debug      Enable debug output
  -h, --help       Show help message

Examples:
  ./cli.sh -m                     Start interactive menu
  ./cli.sh -c config             Load settings from 'config' file
  ./cli.sh -c /path/to/config    Load settings from specified file
  ./cli.sh -c config -m -d       Load config, start menu with debug enabled

Configuration File Format

Create a text file with the following format:

# Jellyfin server URL (required)
URL=http://your-jellyfin-server:8096

# Authentication methods (choose one)
TOKEN=your_api_token_or_access_token
# OR
USERNAME=your_username
PASSWORD=your_password

# Optional: Pre-set user ID
USER_ID=your_user_id

Authentication Priority:

1. If a valid TOKEN is provided, it will be used
2. If TOKEN is invalid/missing and USERNAME/PASSWORD are provided, it will authenticate automatically
3. If no authentication is provided, you'll need to configure it manually

Features Overview

1. Server Management

• Server Info - Display server name, version, and operating system
• Active Sessions - View currently active user sessions
• Connection Configuration - Set up server connection interactively

2. Library Operations

• List Libraries - View all available media libraries
• Recent Items - Show recently added content
• Search Content - Search across all libraries with flexible endpoints

3. User Management

• User Info - Display current user details and activity
• Authentication - Multiple authentication methods with automatic token validation

4. Export Functionality

Export library content in multiple formats:

• JSON Export - Detailed structured data with metadata
• CSV Export - Spreadsheet-compatible format with key fields (Name, Type, Year, Runtime, Path, Date Added)
• Text Export - Simple human-readable list

Export files are automatically named with timestamps: LibraryName_export_20231015_143022.json

Menu Options

1. Configure Connection    - Set up Jellyfin server connection
2. Show Server Info       - Display server information
3. List Libraries         - Show available media libraries
4. List Recent Items      - Display recently added content
5. Search Content         - Search across all libraries
6. List Active Sessions   - Show current user sessions
7. Show User Info         - Display current user details
8. Export Library Content - Export library data to file
9. Exit                   - Quit the application

API Endpoints Used

The client uses various Jellyfin API endpoints:

• /System/Info - Server information
• /Users/authenticatebyname - User authentication
• /Users/Me - Current user information
• /Library/VirtualFolders - Library list
• /Users/{userId}/Items/Latest - Recent items
• /Users/{userId}/Items - Library content and search
• /Sessions - Active sessions
• /Search/Hints - Search functionality

Troubleshooting

Common Issues

1. "Please authenticate first"

   • Ensure your config file has valid credentials
   • Try using debug mode (-d) to see authentication details

2. "Failed to fetch" errors

   • Check your Jellyfin server URL
   • Verify the server is running and accessible
   • Ensure your credentials are correct

3. JSON parsing issues

   • Install jq for better JSON handling
   • The script includes fallback parsing for systems without jq

Debug Mode

Enable debug mode to see detailed API requests and responses:

./cli.sh -c config -m -d

This will show:

• API endpoints being called
• HTTP status codes
• Request/response details
• Authentication information

Security Notes

• Store configuration files securely
• Consider using API tokens instead of passwords
• Tokens can be generated in Jellyfin's admin dashboard under API Keys
• Never commit configuration files with credentials to version control

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Jellyfin Project for the excellent media server
• jq for JSON processing