### Start NeutArr.io Application (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Run this command to start the NeutArr.io application after installing dependencies.

```bash
npm start
```

--------------------------------

### Install Node.js, npm, and Git (Debian/Ubuntu)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Install necessary dependencies for manual installation on Debian-based systems.

```bash
sudo apt update
sudo apt install -y nodejs npm git
```

--------------------------------

### Install Homebrew, Node.js, and Git (macOS)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Install Homebrew, Node.js, and Git on macOS for manual installation.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node git
```

--------------------------------

### Install NeutArr.io with Advanced Options (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Use this command with flags to customize the installation path and port, or to skip dependency installation.

```bash
curl -sSL https://install.neutarr.io | bash -s -- --prefix /opt/neutarr --port 8080
```

--------------------------------

### Start NeutArr.io with Docker Compose (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Run this command in the NeutArr.io directory to start the application using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### Install npm Dependencies (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Install project dependencies using npm after cloning the repository.

```bash
npm install
```

--------------------------------

### Install NeutArr.io with One-line Script (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Execute this command on supported Linux distributions to automate the NeutArr.io installation.

```bash
curl -sSL https://install.neutarr.io | bash
```

--------------------------------

### Install Dependencies with Poetry

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Installs project dependencies using Poetry. Requires Python 3.11+.

```bash
poetry install
```

--------------------------------

### Handle Enter Key Press for Step Advancement

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/setup.html

Listens for the 'Enter' key press to advance the active setup step. It triggers the click event for the next button in the 'accountSetup' or 'authModeSetup' sections.

```javascript
document.addEventListener('keydown', function(e) {
    if (e.key === 'Enter') {
        const activeSection = document.querySelector('.setup-section.active');
        if (!activeSection) return;
        if (activeSection.id === 'accountSetup') {
            accountNextButton.click();
        } else if (activeSection.id === 'authModeSetup') {
            finishButton.click();
        }
    }
});
```

--------------------------------

### Handle Back Button Navigation

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/setup.html

Attaches an event listener to the back button to navigate to the previous setup step.

```javascript
backButton.addEventListener('click', function() {
    goToStep(1);
});
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/CONTRIBUTING.md

Examples of valid commit messages following the Conventional Commits specification. Ensure your commit titles adhere to these patterns.

```text
feat: add readarr quality upgrade support
```

```text
fix: correct ipaddress CIDR validation for local bypass
```

```text
chore: update pyjwt to 2.10.0
```

--------------------------------

### Run NeutArr Server Locally

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Starts the NeutArr server for local development. Setting DEBUG=true enables the Flask development server.

```bash
DEBUG=true NEUTARR_CONFIG_DIR=./config poetry run python main.py
# → Server running at http://localhost:9705
```

--------------------------------

### Get Settings

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves all application settings, including general configuration and specific settings for integrated applications. Requires authentication.

```APIDOC
## GET /api/settings — Read all settings

### Description
Returns the full settings payload for every configured app and global settings. Requires auth.

### Method
GET

### Endpoint
/api/settings

### Response Example
```json
{
  "general": {"debug_mode": false, "ssl_verify": true, "api_timeout": 120, ...},
  "sonarr":  {"instances": [...], "hunt_missing_items": 1, "sleep_duration": 900, ...},
  "radarr":  {"instances": [...], ...},
  ...
}
```
```

--------------------------------

### Run NeutArr Locally

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/README.md

Starts the NeutArr application in debug mode. Access the application at http://localhost:9705.

```bash
DEBUG=true poetry run python main.py
# → http://localhost:9705
```

--------------------------------

### Enable proxy/no-login mode

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Marks the initial setup as skipped, enabling proxy-bypass mode without creating a user account. This is intended for deployments that use external authentication solutions like Authelia or Authentik.

```APIDOC
## POST /api/auth/skip-setup — Enable proxy/no-login mode

Marks setup as skipped, enabling proxy-bypass mode without creating a user account. Intended for deployments behind Authelia or Authentik where authentication is handled externally.

```bash
curl -s -X POST http://localhost:9705/api/auth/skip-setup
# → {"setup_skipped": true, "success": true}
```
```

--------------------------------

### Update NeutArr.io Manually

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Use these commands to update NeutArr.io when installed manually. Ensure you are in the NeutArr.io directory.

```bash
cd /path/to/NeutArr.io
git pull
npm install
npm restart
```

--------------------------------

### Enable Proxy Authentication Mode

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

This endpoint marks the initial setup as skipped, enabling proxy-bypass mode without creating a user account. It is intended for deployments where authentication is handled externally by systems like Authelia or Authentik.

```bash
curl -s -X POST http://localhost:9705/api/auth/skip-setup
# → {"setup_skipped": true, "success": true}
```

--------------------------------

### Schedule Data Structure Example

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/features/scheduling.html

This JSON structure represents a single schedule configuration within NeutArr. It includes details like the action to perform, timing, target app, and enablement status.

```json
{
  "id": "unique-schedule-id",
  "action": "search_missing",
  "time": "13:30",
  "days": ["monday", "wednesday", "friday"],
  "app": "Main Sonarr",
  "enabled": true,
  "appType": "sonarr"
}
```

--------------------------------

### Update NeutArr.io via Docker

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Use these commands to update NeutArr.io when installed using Docker. Ensure you are in the NeutArr.io directory.

```bash
cd /path/to/NeutArr.io
git pull
docker-compose pull
docker-compose up -d
```

--------------------------------

### Get Stateful Management Info

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves information about the current stateful lock, including creation timestamp, expiration timestamp, and processing interval.

```bash
# Get current stateful state (creation time, expiry, interval)
curl -s -b cookies.txt http://localhost:9705/api/stateful/info | jq .
```

--------------------------------

### Get Scheduler Execution History

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the in-memory history of scheduler runs, including timestamps and the result of each run (e.g., started, skipped).

```bash
curl -s -b cookies.txt http://localhost:9705/api/scheduler/history | jq .
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/README.md

Use Python's built-in HTTP server to test documentation changes locally. Navigate to the docs directory and run the command.

```bash
cd /path/to/Huntarr.io/docs
python -m http.server 8000
```

--------------------------------

### Set Up First-Run Admin Account

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

This endpoint is used to create the initial administrator user account. It only functions when no users have been previously created. Upon successful creation, it returns JWT access and refresh tokens and sets corresponding session cookies.

```bash
curl -s -X POST http://localhost:9705/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "SecurePass123",
    "confirm_password": "SecurePass123"
  }'
# → {
#     "access_token": "eyJ...",
#     "refresh_token": "eyJ...",
#     "token_type": "bearer",
#     "username": "admin"
#   }
```

--------------------------------

### Read and Write Per-App Settings

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Use these endpoints to read or write settings for specific applications like Sonarr, Radarr, etc. The POST request can be used to add new configurations, such as a second instance.

```bash
# Read Sonarr settings
curl -s -b cookies.txt http://localhost:9705/api/settings/sonarr | jq .
# → {
#     "instances": [{"name": "Main", "api_url": "http://sonarr:8989", "api_key": "abc123", "enabled": true}],
#     "hunt_missing_items": 1,
#     "hunt_upgrade_items": 0,
#     "upgrade_mode": "episodes",
#     "hunt_missing_mode": "episodes",
#     "sleep_duration": 900,
#     "monitored_only": true,
#     "skip_future_episodes": true,
#     "hourly_cap": 20
#   }

# Save Sonarr settings (add a second instance)
curl -s -b cookies.txt -X POST http://localhost:9705/api/settings/sonarr \
  -H "Content-Type: application/json" \
  -d '{
    "instances": [
      {"name": "Main",    "api_url": "http://sonarr:8989",  "api_key": "key1", "enabled": true},
      {"name": "Anime",   "api_url": "http://sonarr2:8989", "api_key": "key2", "enabled": true}
    ],
    "hunt_missing_items": 2,
    "hunt_upgrade_items": 1,
    "sleep_duration": 1800,
    "monitored_only": true,
    "hourly_cap": 15
  }'
# → {"success": true}
```

--------------------------------

### Get API Key

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the auto-generated API key used for automation and integrations. Requires authentication.

```APIDOC
## GET /api/auth/apikey — Retrieve the API key

### Description
Returns the auto-generated API key used for automation and integrations. Requires JWT or API key auth.

### Method
GET

### Endpoint
/api/auth/apikey

### Response Example
```json
{
  "api_key": "xK9mP2nQrT4vW7yZ..."
}
```
```

--------------------------------

### Get Auth Status

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the current authentication status and configuration, useful for frontend to determine UI elements.

```APIDOC
## GET /api/auth/status — Current auth state

### Description
Public endpoint; returns the current authentication configuration for the frontend to determine which UI elements to display.

### Method
GET

### Endpoint
/api/auth/status

### Response Example
```json
{
  "auth_enabled": true,
  "has_users": true,
  "instance_storage_key": "inst_a1b2c3d4e5f6",
  "local_access_bypass": false,
  "proxy_auth_bypass": false,
  "setup_skipped": false
}
```
```

--------------------------------

### Navigate to NeutArr.io Directory (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Change your current directory to the cloned NeutArr.io repository.

```bash
cd NeutArr.io
```

--------------------------------

### Retrieve All Settings

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Fetches the complete settings payload, including global configurations and settings for all integrated applications. Authentication is required to access this endpoint.

```bash
curl -s -b cookies.txt http://localhost:9705/api/settings | jq .
# → {
#     "general": {"debug_mode": false, "ssl_verify": true, "api_timeout": 120, ...},
#     "sonarr":  {"instances": [...], "hunt_missing_items": 1, "sleep_duration": 900, ...},
#     "radarr":  {"instances": [...], ...},
#     ...
#   }
```

--------------------------------

### JavaScript EventSource for Logs

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Example of using the JavaScript EventSource API to stream Sonarr logs in real-time. Handles messages and errors.

```javascript
const source = new EventSource('/logs?app=sonarr');
source.onmessage = (e) => console.log(e.data);
source.onerror   = ()  => source.close();
```

--------------------------------

### Docker Compose Configuration for NeutArr.io

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

A sample docker-compose.yml file for running NeutArr.io. Customize paths and environment variables as needed.

```yaml
version: '3'
services:
  neutarr:
    image: iampuid0/neutarr:latest
    container_name: neutarr
    ports:
      - 9705:9705
    volumes:
      - ./config:/config
      - /path/to/media:/media
      - /path/to/downloads:/downloads
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
    restart: unless-stopped
```

--------------------------------

### Initialize Theme Preference and Apply Styles

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/login.html

This JavaScript code checks for user theme preferences (dark mode) in local storage and applies dark theme styles to the document. It also includes inline styles to prevent a flash of unstyled content.

```javascript
NEUTARR_INSTANCE_STORAGE_KEY = {{ instance_storage_key|tojson }};
// Check theme preference immediately before any rendering
(function() {
  var prefersDarkMode = localStorage.getItem('neutarr-dark-mode') === 'true';
  if (prefersDarkMode || window.matchMedia('(prefers-color-scheme: dark)').matches) {
    document.documentElement.classList.add('dark-theme');
    // Add inline styles to prevent flash
    document.write('<style>body, html { background-color: #1a1d24 !important; color: #f8f9fa !important; } .login-container { background-color: #252a34 !important; } .login-header { background-color: #121212 !important; }</style>');
  }
})();
```

--------------------------------

### Get Authentication Status

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the current authentication configuration, which is useful for the frontend to dynamically adjust UI elements based on the auth state.

```bash
curl -s http://localhost:9705/api/auth/status
# → {
#     "auth_enabled": true,
#     "has_users": true,
#     "instance_storage_key": "inst_a1b2c3d4e5f6",
#     "local_access_bypass": false,
#     "proxy_auth_bypass": false,
#     "setup_skipped": false
#   }
```

--------------------------------

### Get Hourly API Usage Caps

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Returns the current hourly API call counts for each application and their configured caps. This endpoint is useful for monitoring rate-limit headroom.

```bash
curl -s -b cookies.txt http://localhost:9705/api/hourly-caps | jq .
# → {
#     "success": true,
#     "caps":   {"sonarr": 7, "radarr": 3, "lidarr": 0, "readarr": 0, "whisparr": 0, "eros": 0},
#     "limits": {"sonarr": 20, "radarr": 20, "lidarr": 20, "readarr": 20, "whisparr": 20, "eros": 20}
#   }
```

--------------------------------

### First-run account creation

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Creates the initial administrator user account. This endpoint is only functional when no users have been previously created. It returns a JWT token pair and sets session cookies upon successful creation.

```APIDOC
## POST /api/auth/setup — First-run account creation

Creates the single admin user. Only works when no users exist yet. Returns a JWT token pair and sets session cookies.

```bash
curl -s -X POST http://localhost:9705/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "SecurePass123",
    "confirm_password": "SecurePass123"
  }'
# → {
#     "access_token": "eyJ...",
#     "refresh_token": "eyJ...",
#     "token_type": "bearer",
#     "username": "admin"
#   }
```
```

--------------------------------

### Get Media Hunt Statistics

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves cumulative statistics for missing items found and quality upgrades triggered across all configured applications. This is useful for monitoring hunting activity.

```bash
curl -s -b cookies.txt http://localhost:9705/api/stats | jq .
# → {
#     "success": true,
#     "stats": {
#       "sonarr":  {"missing_hunted": 45, "upgrades_triggered": 12},
#       "radarr":  {"missing_hunted": 23, "upgrades_triggered":  4},
#       "lidarr":  {"missing_hunted":  8, "upgrades_triggered":  1},
#       "readarr": {"missing_hunted":  3, "upgrades_triggered":  0},
#       "whisparr":{"missing_hunted":  0, "upgrades_triggered":  0}
#     }
#   }
```

--------------------------------

### Get NeutArr Runtime Version

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the currently running version of NeutArr. The version is determined by the `NEUTARR_VERSION` environment variable, falling back to `pyproject.toml`, and finally a hardcoded default.

```bash
curl -s http://localhost:9705/api/version
# → 1.6.1
```

--------------------------------

### Jinja2 Template Includes

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/scheduling.html

Includes standard footer and script components into the HTML template.

```html
{% include 'components/footer.html' %} {% include 'components/scripts.html' %}
```

--------------------------------

### Reset App Settings to Defaults

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Use this endpoint to reset the settings for a specific application back to their default values. An error is returned if an invalid or missing app name is provided.

```bash
curl -s -b cookies.txt -X POST http://localhost:9705/api/settings/reset \
  -H "Content-Type: application/json" \
  -d '{"app": "sonarr"}'
# → {"success": true}
# Error: → {"success": false, "error": "Invalid or missing app name: badapp"}
```

--------------------------------

### Get Local Access Bypass Status

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

This public endpoint is used by the frontend to determine whether to hide the user-menu (login/logout controls). It returns `true` when any bypass mode is active, and `false` otherwise.

```APIDOC
## GET /api/get_local_access_bypass_status

### Description
Public endpoint the frontend uses to decide whether to hide the user-menu (login/logout controls). Returns `true` when any bypass mode is active.

### Method
GET

### Endpoint
/api/get_local_access_bypass_status

### Response
#### Success Response (200)
- **isEnabled** (boolean) - Indicates if bypass mode is active.

### Request Example
```bash
curl -s http://localhost:9705/api/get_local_access_bypass_status
```

### Response Example
```json
{
  "isEnabled": true
}
```
```

--------------------------------

### Sonarr/Radarr Instance Configuration

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Defines connection details for multiple *arr application instances.

```json
{
  "instances": [
    {
      "name": "Main Sonarr",
      "api_url": "http://sonarr:8989",
      "api_key": "your-sonarr-api-key",
      "enabled": true
    },
    {
      "name": "Anime Sonarr",
      "api_url": "http://sonarr-anime:8989",
      "api_key": "your-anime-sonarr-api-key",
      "enabled": true
    }
  ],
  "hunt_missing_items": 1,
  "hunt_upgrade_items": 1,
  "upgrade_mode": "episodes",
  "hunt_missing_mode": "episodes",
  "sleep_duration": 900,
  "monitored_only": true,
  "skip_future_episodes": true,
  "hourly_cap": 20
}
```

--------------------------------

### Load Scheduler Configuration

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Retrieves the current automated search schedule configuration. This shows time windows and days for each app.

```bash
# Load current schedules
curl -s -b cookies.txt http://localhost:9705/api/scheduler/load | jq .
```

--------------------------------

### Per-app settings

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Read or write settings for a specific app. Valid app_name values include sonarr, radarr, lidarr, readarr, whisparr, eros, swaparr, and general.

```APIDOC
## GET /api/settings/{app_name} and POST /api/settings/{app_name} 

### Description
Read or write settings for a specific app. Valid `app_name` values: `sonarr`, `radarr`, `lidarr`, `readarr`, `whisparr`, `eros`, `swaparr`, `general`.

### Method
GET, POST

### Endpoint
`/api/settings/{app_name}`

### Parameters
#### Path Parameters
- **app_name** (string) - Required - The name of the application whose settings are being accessed.

### Request Example (POST)
```json
{
  "instances": [
    {"name": "Main",    "api_url": "http://sonarr:8989",  "api_key": "key1", "enabled": true},
    {"name": "Anime",   "api_url": "http://sonarr2:8989", "api_key": "key2", "enabled": true}
  ],
  "hunt_missing_items": 2,
  "hunt_upgrade_items": 1,
  "sleep_duration": 1800,
  "monitored_only": true,
  "hourly_cap": 15
}
```

### Response (GET)
#### Success Response (200)
- **instances** (array) - List of configured app instances.
- **hunt_missing_items** (integer) - Number of missing items to hunt.
- **hunt_upgrade_items** (integer) - Number of items to hunt for upgrades.
- **upgrade_mode** (string) - Mode for upgrading items.
- **hunt_missing_mode** (string) - Mode for hunting missing items.
- **sleep_duration** (integer) - Duration in seconds to sleep between hunts.
- **monitored_only** (boolean) - Whether to only consider monitored items.
- **skip_future_episodes** (boolean) - Whether to skip future episodes.
- **hourly_cap** (integer) - The hourly API call cap for the app.

### Response Example (GET)
```json
{
  "instances": [{"name": "Main", "api_url": "http://sonarr:8989", "api_key": "abc123", "enabled": true}],
  "hunt_missing_items": 1,
  "hunt_upgrade_items": 0,
  "upgrade_mode": "episodes",
  "hunt_missing_mode": "episodes",
  "sleep_duration": 900,
  "monitored_only": true,
  "skip_future_episodes": true,
  "hourly_cap": 20
}
```

### Response Example (POST)
```json
{"success": true}
```
```

--------------------------------

### Table and App Panel Positioning

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/components/apps_section.html

Ensures tables are positioned correctly at the bottom and app panels have appropriate padding.

```css
/* Proper table positioning at bottom */
.app-panels-container {
  margin-top: auto;
  padding: 10px 0 0;
  width: 100%;
}

/* Ensure Additional Options section is fully visible */
#sonarrApps, #radarrApps, #lidarrApps, #readarrApps, #whisparrApps, #erosApps, #swaparrApps {
  padding-bottom: 150px;
  /* Extra padding to ensure bottom content is visible */
  margin-bottom: 50px;
}

/* Add explicit styling for the Additional Options section */
.additional-options-section, .additional-options {
  margin-bottom: 100px;
  padding-bottom: 100px;
}

/* Ensure Skip Series Refresh is visible */
.skip-series-refresh {
  margin-bottom: 50px;
  padding-bottom: 50px;
}

/* Panel styling */
.app-apps-panel {
  padding-bottom: 10px;
  min-height: 0;
  height: auto;
}
```

--------------------------------

### Read and Set Authentication Mode

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Allows reading the current authentication mode or switching between 'login', 'local_bypass', and 'no_login' modes. 'local_bypass' allows LAN IPs to skip login, while 'no_login' is for proxy/SSO bypass scenarios.

```bash
# Read current mode
curl -s -b cookies.txt http://localhost:9705/api/auth/mode
# → {"auth_mode": "login"}
```

```bash
# Switch to local-bypass mode (LAN IPs skip the login page)
curl -s -b cookies.txt -X POST http://localhost:9705/api/auth/mode \
  -H "Content-Type: application/json" \
  -d '{"auth_mode": "local_bypass"}'
# → {"success": true}
```

```bash
# Switch to proxy-bypass mode (behind Authelia/Authentik)
curl -s -b cookies.txt -X POST http://localhost:9705/api/auth/mode \
  -H "Content-Type: application/json" \
  -d '{"auth_mode": "no_login"}'
# → {"success": true}
```

--------------------------------

### Clone NeutArr.io Repository (Bash)

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Use this command to clone the NeutArr.io repository from GitHub.

```bash
git clone https://github.com/plexguide/NeutArr.io.git
```

--------------------------------

### Retrieve and Use API Key

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Fetches the auto-generated API key for automation. The key can then be used in subsequent requests via the 'X-Api-Key' header or as a query parameter.

```bash
API_KEY=$(curl -s -b cookies.txt http://localhost:9705/api/auth/apikey | jq -r .api_key)
echo "API Key: $API_KEY"
# → API Key: xK9mP2nQrT4vW7yZ...

# Using the API key for subsequent requests (header or query param):
curl -s -H "X-Api-Key: $API_KEY" http://localhost:9705/api/settings
curl -s "http://localhost:9705/api/settings?apikey=$API_KEY"
```

--------------------------------

### Perform Security Scan with Bandit

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/README.md

Runs a static analysis security scan on the project's source code using Bandit to identify potential vulnerabilities.

```bash
poetry run bandit -r src/ main.py -ll
```

--------------------------------

### Handle Account Creation Form Submission

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/setup.html

Handles the submission of the account creation form. It sends user credentials to the server and processes the response, showing success or error messages. Includes error handling and UI state management.

```javascript
accountNextButton.addEventListener('click', async function() {
    hideError(accountError);
    const username = usernameInput.value;
    const password = passwordInput.value;
    const originalText = accountNextButton.innerHTML;
    accountNextButton.innerHTML = '<i class="fas fa-spinner fa-spin"></i> Creating...';
    accountNextButton.disabled = true;
    try {
        const response = await fetch('/api/account/create', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ username, password })
        });
        const data = await response.json();
        if (response.ok) {
            // Assuming data.refresh_token, data.username are returned on success
            // The actual parameters passed to goToStep might differ based on your application's logic
            goToStep(2); // Proceed to the next step on success
        } else {
            showError(accountError, data.error || 'Failed to create account.');
        }
    } catch (err) {
        console.error('Setup error:', err);
        showError(accountError, 'An error occurred. Please try again.');
    } finally {
        accountNextButton.innerHTML = originalText;
        accountNextButton.disabled = false;
    }
});
```

--------------------------------

### Fetch Application Version with JavaScript

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/components/topbar.html

Fetches the application version from the '/api/version' endpoint and updates the element with the ID 'version-value'. Handles potential fetch errors.

```javascript
document.addEventListener('DOMContentLoaded', function () {
  var el = document.getElementById('version-value');
  if (el) {
    fetch('/api/version').then(function (r) {
      return r.text();
    }).then(function (v) {
      el.textContent = v.trim();
    }).catch(function () {
      // Optionally handle error, e.g., display a message
    });
  }
});
```

--------------------------------

### Responsive Styles for Support Links

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/components/home_section.html

Applies responsive adjustments to the layout and sizing of support links based on screen width. Styles are applied for screens up to 768px and then further refined for screens up to 480px.

```css
media (max-width: 768px) { .support-links-grid { gap: 8px; } .support-link { padding: 15px; } .support-link .icon-container { width: 42px; height: 42px; font-size: 1.3rem; margin-right: 12px; } .support-link .link-title { font-size: 0.95rem; } .support-link .link-description { font-size: 0.75rem; } }
/* Even smaller screens */
@media (max-width: 480px) { .support-links-grid { grid-template-columns: 1fr; } }
```

--------------------------------

### Find User ID and Group ID

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/getting-started/installation.html

Run this command to find your user ID and group ID, which may be needed for permission troubleshooting in Docker.

```bash
id $(whoami)
```

--------------------------------

### Handle Finish Button - Save Authentication Mode and Redirect

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/setup.html

Saves the selected authentication mode and then redirects the user to the homepage. It handles API requests, response processing, and UI feedback during the saving process.

```javascript
finishButton.addEventListener('click', async function() {
    hideError(authModeError);
    const selectedMode = authModeSelect.value;
    const originalText = finishButton.innerHTML;
    finishButton.innerHTML = '<i class="fas fa-spinner fa-spin"></i> Saving...';
    finishButton.disabled = true;
    try {
        const response = await authFetch('/api/settings/general', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                local_access_bypass: selectedMode === 'local_bypass',
                proxy_auth_bypass: selectedMode === 'no_login',
            }),
        });
        if (response.ok) {
            window.location.href = '/';
        } else {
            const data = await response.json().catch(() => ({}));
            showError(authModeError, data.error || 'Failed to save settings.');
            finishButton.innerHTML = originalText;
            finishButton.disabled = false;
        }
    } catch (err) {
        console.error('Settings save error:', err);
        showError(authModeError, 'An error occurred. Please try again.');
        finishButton.innerHTML = originalText;
        finishButton.disabled = false;
    }
});
```

--------------------------------

### Check App Connection Status

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

This endpoint returns the connection status for a configured application and all its associated instances. It indicates how many instances are currently connected out of the total configured.

```bash
curl -s -b cookies.txt http://localhost:9705/api/status/sonarr | jq .
# → {"connected_count": 2, "total_configured": 2}

curl -s -b cookies.txt http://localhost:9705/api/status/radarr | jq .
# → {"connected_count": 1, "total_configured": 1}

# Unconfigured or unreachable:
# → {"connected_count": 0, "total_configured": 1}
```

--------------------------------

### Style Apps Dropdown Options

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/frontend/templates/components/apps_section.html

Ensures proper left padding for options within the apps dropdown select element.

```css
/* Style for apps dropdown to ensure the text has proper padding */
#appsAppSelect option {
  padding-left: 10px;
}
```

--------------------------------

### Docker Compose Deployment for NeutArr

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

This Docker Compose configuration sets up NeutArr with persistent storage for settings, exposes the web UI port, and configures user/group IDs for correct file ownership. Optional environment variables allow for port, debug, and configuration directory overrides, as well as trusted proxy CIDRs.

```yaml
services:
  neutarr:
    image: iampuid0/neutarr:latest
    container_name: neutarr
    restart: unless-stopped
    ports:
      - "9705:9705"
    volumes:
      - ./config:/config
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      # Optional overrides:
      # - PORT=9705
      # - DEBUG=false
      # - NEUTARR_CONFIG_DIR=/config
      # - TRUSTED_PROXIES=172.18.0.0/16   # trust X-Forwarded-For from this CIDR
```

--------------------------------

### Check app connection status

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Returns connection status for a configured app and all its instances.

```APIDOC
## GET /api/status/{app_name} 

### Description
Returns connection status for a configured app and all its instances.

### Method
GET

### Endpoint
`/api/status/{app_name}`

### Parameters
#### Path Parameters
- **app_name** (string) - Required - The name of the application to check the status for.

### Response
#### Success Response (200)
- **connected_count** (integer) - The number of currently connected instances.
- **total_configured** (integer) - The total number of configured instances for the app.

### Response Example
```json
{"connected_count": 2, "total_configured": 2}
```

### Response Example (Unconfigured or unreachable)
```json
{"connected_count": 0, "total_configured": 1}
```
```

--------------------------------

### Retrieve Sonarr History with Pagination

Source: https://context7.com/i-am-puid-0/neutarr/llms.txt

Fetches a paginated list of Sonarr media history entries. Specify page number and results per page.

```bash
# Page 1, 20 results for Sonarr
curl -s -b cookies.txt "http://localhost:9705/api/history/sonarr?page=1&page_size=20" | jq .
```

--------------------------------

### Add Information Link to NeutArr.io UI

Source: https://github.com/i-am-puid-0/neutarr/blob/dev/docs/apps/index.html

Use this HTML snippet to add an information icon linking to specific application documentation within your NeutArr.io UI. Ensure the href attribute points to the correct documentation page.

```html
<a href="https://plexguide.github.io/NeutArr.io/apps/sonarr.html" class="info-link" target="_blank">i</a>
```