Yarr

A Terminal User Interface (TUI) for managing Sonarr, built as a Rust workspace with separate API client library.

> ✨ Note: This project was fully vibe coded with AI assistance, showcasing modern development workflows and comprehensive feature implementation.

Project Structure

This workspace contains two crates:

• yarr-api - A standalone Rust library for interacting with the Sonarr API
• yarr-cli - The main TUI application that uses the API library

Features

• View system status and health
• Browse series and episodes
• Monitor download queue
• View download history
• Interactive TUI interface with vim-like keybind support
• Configurable UI preferences and keybind modes
• In-app configuration editing for Sonarr connection and UI settings
• Configurable via config files, environment variables, or CLI arguments

Installation

Install the TUI Application

cargo install --path yarr-cli

Use the API Library

Add to your Cargo.toml:

[dependencies]
yarr-api = { path = "yarr-api" }

Configuration

Yarr supports multiple configuration methods with the following priority order (highest to lowest):

1. Command line arguments
2. Environment variables
3. Configuration file
4. Default values

Configuration File

Create a configuration file in one of these locations:

• ./yarr.toml (current directory)
• ~/.config/yarr/config.toml (user config directory)

Example configuration:

[sonarr]
url = "http://localhost:8989"
api_key = "your-api-key-here"

[ui]
# Keybind mode: "Normal" or "Vim"
keybind_mode = "Normal"
# Show help text in footer
show_help = true

Environment Variables

Set these environment variables:

export YARR_SONARR_URL="http://localhost:8989"
export YARR_SONARR_API_KEY="your-api-key-here"
export YARR_UI_KEYBIND_MODE="Vim"
export YARR_UI_SHOW_HELP="true"

Command Line Arguments

yarr --sonarr-url="http://localhost:8989" --sonarr-api-key="your-api-key"

Usage

TUI Mode (Default)

Launch the interactive TUI:

yarr
# or explicitly
yarr tui

Command Line Mode

List all series:

yarr list

List only monitored series:

yarr list --monitored

Add a new series:

yarr add --name "Series Name"

Configuration Management

Create a sample config file:

yarr config init

Create config file at specific location:

yarr config init --path /path/to/config.toml

Show current configuration:

yarr config show

Show configuration file search paths:

yarr config paths

Edit configuration file with your preferred editor:

yarr config edit

Edit specific config file:

yarr config edit --path /path/to/config.toml

Shell Completions

Generate shell completions:

# Bash
yarr completions bash > /etc/bash_completion.d/yarr

# Zsh
yarr completions zsh > ~/.zfunc/_yarr

# Fish
yarr completions fish > ~/.config/fish/completions/yarr.fish

# PowerShell
yarr completions powershell > yarr.ps1

TUI Controls

Normal Mode (Default)

• q - Quit
• ↑/↓ or j/k - Navigate up/down
• Enter - Select/expand
• Tab - Switch between tabs
• d - Toggle details
• r - Refresh data
• / - Search (in Search tab)
• s - Save configuration changes

Vim Mode

• q - Quit
• h/j/k/l - Navigate left/down/up/right
• w/b - Next/previous tab
• gg - Go to first item
• G - Go to last item
• v - Toggle details (visual mode)
• u - Refresh data (undo)
• / - Search mode
• i - Insert/input mode
• s - Save configuration changes

Settings Tab

Use the Settings tab to:

• Toggle between Normal and Vim keybind modes
• Enable/disable help text display
• Edit Sonarr server URL and API key
• Save configuration changes to file

Access the Settings tab by navigating to the last tab or pressing Tab repeatedly.

In-App Configuration

You can configure Sonarr connection settings directly within the application:

1. Navigate to the Settings tab
2. Select "Sonarr URL" or "API Key" and press Enter
3. Type the new value and press Enter to save
4. Press 's' to save all changes to the config file

This eliminates the need to manually edit config files for basic setup.

Getting Started

1. Install yarr
2. Create a configuration file:

   yarr config init
   

3. Edit the configuration file to set your Sonarr URL and API key
4. Launch the TUI:

   yarr
   

Finding Your Sonarr API Key

1. Open your Sonarr web interface
2. Go to Settings > General
3. Find the "Security" section
4. Copy the "API Key" value

API Library Usage

The yarr-api crate can be used independently in your own projects:

use yarr_api::{SonarrClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = SonarrClient::new(
        "http://localhost:8989".to_string(),
        "your-api-key".to_string()
    );

    let series = client.get_series().await?;
    println!("Found {} series", series.len());

    Ok(())
}

See the yarr-api README for detailed API documentation and examples.

Development

Building the Workspace

# Build all crates
cargo build

# Build just the CLI
cargo build -p yarr

# Build just the API library
cargo build -p yarr-api

# Run tests
cargo test

# Run the API library example
cargo run --example basic_usage

License

MIT