yarr/README.md

# 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

```bash
cargo install --path yarr-cli
```

### Use the API Library

Add to your `Cargo.toml`:

```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:

```toml
[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:

```bash
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

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

## Usage

### TUI Mode (Default)

Launch the interactive TUI:

```bash
yarr
# or explicitly
yarr tui
```

### Command Line Mode

List all series:

```bash
yarr list
```

List only monitored series:

```bash
yarr list --monitored
```

Add a new series:

```bash
yarr add --name "Series Name"
```

### Configuration Management

Create a sample config file:

```bash
yarr config init
```

Create config file at specific location:

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

Show current configuration:

```bash
yarr config show
```

Show configuration file search paths:

```bash
yarr config paths
```

Edit configuration file with your preferred editor:

```bash
yarr config edit
```

Edit specific config file:

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

### Shell Completions

Generate shell completions:

```bash
# 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:
   ```bash
   yarr config init
   ```
3. Edit the configuration file to set your Sonarr URL and API key
4. Launch the TUI:
   ```bash
   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:

```rust
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](yarr-api/README.md) for detailed API documentation and examples.

## Development

### Building the Workspace

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