### Start Huntarr.io Application

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Run this command in the Huntarr.io directory to start the application after installing dependencies.

```bash
npm start
```

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

### Complete Setup Navigation

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Redirects the user to the root path ('/') upon clicking the 'Finish Setup' button, indicating the completion of the setup process.

```javascript
finishSetupButton.addEventListener('click', function() { window.location.href = '/'; });
```

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

### Show Setup Step Function

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Manages the visibility of different setup sections (Account, 2FA, Auth Mode, Complete) and updates the visual indicators for completed steps. Call this function to navigate between setup stages.

```javascript
function showStep(step) { steps.forEach((s, index) => { if (index + 1 < step) { s.classList.remove('active'); s.classList.add('completed'); } else if (index + 1 === step) { s.classList.add('active'); s.classList.remove('completed'); } else { s.classList.remove('active'); s.classList.remove('completed'); } }); // For the four sections: Account, 2FA, Auth Mode, Complete if (step === 1) { document.getElementById('accountSetup').classList.add('active'); document.getElementById('twoFactorSetup').classList.remove('active'); document.getElementById('authModeSetup').classList.remove('active'); document.getElementById('setupComplete').classList.remove('active'); } else if (step === 2) { document.getElementById('accountSetup').classList.remove('active'); document.getElementById('twoFactorSetup').classList.add('active'); document.getElementById('authModeSetup').classList.remove('active'); document.getElementById('setupComplete').classList.remove('active'); } else if (step === 3) { document.getElementById('accountSetup').classList.remove('active'); document.getElementById('twoFactorSetup').classList.remove('active'); document.getElementById('authModeSetup').classList.add('active'); document.getElementById('setupComplete').classList.remove('active'); } else if (step === 4) { document.getElementById('accountSetup').classList.remove('active'); document.getElementById('twoFactorSetup').classList.remove('active'); document.getElementById('authModeSetup').classList.remove('active'); document.getElementById('setupComplete').classList.add('active'); } currentStep = step; }
```

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

### Install Homebrew, Node.js, and Git on macOS

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Install Homebrew, then use it to install Node.js and Git on macOS.

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

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

### Install Node.js and npm Dependencies

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Install Node.js, npm, and Git on Debian/Ubuntu systems, then install Huntarr.io npm dependencies.

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

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

### Initialize Setup Page Elements and State

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Sets up event listeners and initializes variables for tracking the current step and user data. It selects DOM elements needed for the setup process.

```javascript
document.addEventListener('DOMContentLoaded', function() { // Elements const steps = document.querySelectorAll('.step'); const screens = document.querySelectorAll('.setup-section'); const errorMessage = document.getElementById('errorMessage'); // Account setup elements const usernameInput = document.getElementById('username'); const passwordInput = document.getElementById('password'); const confirmPasswordInput = document.getElementById('confirm_password'); const accountNextButton = document.getElementById('accountNextButton'); // 2FA setup elements const qrCodeElement = document.getElementById('qrCode'); const secretKeyElement = document.getElementById('secretKey'); const verificationCodeInput = document.getElementById('verificationCode'); const skip2FALink = document.getElementById('skip2FALink'); const twoFactorNextButton = document.getElementById('twoFactorNextButton'); // Auth Mode setup elements const authModeSelect = document.getElementById('auth_mode'); const authModeNextButton = document.getElementById('authModeNextButton'); const authModeErrorMessage = document.getElementById('authModeErrorMessage'); // Complete setup elements const finishSetupButton = document.getElementById('finishSetupButton'); // Current step tracking let currentStep = 1; let accountCreated = false; let twoFactorEnabled = false; // Store user data let userData = { username: '', password: '' };
```

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

### Install Huntarr.io with Custom Options

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

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

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

### Individual Setup Step Styling (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles each step in the setup navigation, providing padding, background, rounded corners, and font styling. Sets initial opacity and border.

```css
.step {
  padding: 10px;
  background: rgba(28, 36, 54, 0.6);
  border-radius: 10px;
  font-weight: 500;
  flex: 1;
  text-align: center;
  margin: 0;
  opacity: 0.6;
  font-size: 0.85em;
  transition: all 0.3s ease;
  border: 1px solid rgba(90, 109, 137, 0.2);
  color: rgba(255, 255, 255, 0.7);
}
```

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

### Handle Setup Step Navigation

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Manages the click events for navigation buttons across different setup steps. Ensures the correct button is clicked based on the current step.

```javascript
NextButton.click(); } else if (currentStep === 3 && document.activeElement !== authModeNextButton) { authModeNextButton.click(); } else if (currentStep === 4 && document.activeElement !== finishSetupButton) { finishSetupButton.click(); } }
```

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

### Install Huntarr.io with One-line Script

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Execute this command on Linux systems to automate the Huntarr.io installation process.

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

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

### Completed Setup Step Styling (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles completed steps in the setup navigation with a green gradient background, white text, and full opacity. Includes a border and shadow for visual distinction.

```css
.step.completed {
  background: linear-gradient(135deg, #28a745 0%, #34ce57 100%);
  color: white;
  opacity: 1;
  border-color: rgba(40, 167, 69, 0.3);
}
```

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

### Setup Section Visibility (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Controls the display of setup sections, initially hiding them. Applies a fade-in animation when a section becomes active.

```css
/* Form styling */
.setup-section {
  display: none;
  animation: fadeIn 0.3s ease;
}
.setup-section.active {
  display: block;
}
@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(5px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

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

### Skip 2FA Setup

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Handles the click event for the 'Skip 2FA' link, advancing the setup process to the next step (Auth Mode).

```javascript
skip2FALink.addEventListener('click', function() { showStep(3); // Go to Auth Mode step });
```

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

### Active Setup Step Styling (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles the currently active step in the setup navigation. It uses a gradient background, white text, full opacity, a distinct border, and a subtle shadow, with a slight upward transform.

```css
.step.active {
  background: linear-gradient(135deg, #50762E 0%, #6a8e3a 100%);
  color: white;
  opacity: 1;
  border-color: rgba(80, 118, 46, 0.3);
  box-shadow: 0 4px 10px rgba(80, 118, 46, 0.2);
  transform: translateY(-2px);
}
```

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

### Setup Steps Navigation Styling (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles the navigation bar for setup steps, using flexbox to space out individual steps. Includes gap between steps and initial styling for step elements.

```css
/* Setup steps navigation */
.setup-steps {
  display: flex;
  justify-content: space-between;
  margin-bottom: 20px;
  gap: 10px;
}
```

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

### Handle 2FA Setup Errors

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Logs errors encountered during the 2FA setup process and displays a user-friendly error message.

```javascript
.catch(error => { console.error('Error generating 2FA:', error); // Display the specific error message caught showError('Failed to generate 2FA setup: ' + error.message); });
```

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

### 2FA Setup API Call

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Makes a POST request to the /api/user/2fa/setup endpoint to initiate the two-factor authentication setup. Handles specific unauthorized errors and general server errors.

```javascript
// Specify POST method .then(response => { // Check for unauthorized specifically if (response.status === 401) { throw new Error('Unauthorized - Session likely not established yet.'); } if (!response.ok) { // Try to parse error from JSON response return response.json().then(errData => { throw new Error(errData.error || `Server error: ${response.status}`); }).catch(() => { // Fallback if response is not JSON throw new Error(`Server error: ${response.status}`); }); } return response.json(); })
```

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

### Get Version

Source: https://context7.com/elfhosted/newtarr/llms.txt

Serves the version string from the bundled version.txt file.

```APIDOC
## GET /version.txt

### Description
Serves the version string of the NewtArr application.

### Method
GET

### Endpoint
/version.txt

### Request Example
```bash
curl http://localhost:9705/version.txt
```

### Response
#### Success Response (200)
- **version** (string) - The current version of the application.

### Response Example
```
1.0.0
```
```

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

### Default Sonarr Configuration

Source: https://context7.com/elfhosted/newtarr/llms.txt

Example of the default configuration file for Sonarr, used when no configuration exists on first run.

```json
// src/primary/default_configs/sonarr.json
{
  "instances": [
    { "name": "Default", "api_url": "", "api_key": "", "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
}

```

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

### Default General Configuration

Source: https://context7.com/elfhosted/newtarr/llms.txt

Example of the default general configuration file, controlling global settings like debug mode and API timeouts.

```json
// src/primary/default_configs/general.json
{
  "debug_mode": false,
  "log_refresh_interval_seconds": 30,
  "ui_theme": "dark",
  "proxy_auth_bypass": true,
  "stateful_management_hours": 168,
  "command_wait_delay": 1,
  "command_wait_attempts": 600,
  "minimum_download_queue_size": -1,
  "api_timeout": 120,
  "ssl_verify": true
}

```

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

### Run Huntarr.io with Docker Compose

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Start Huntarr.io and its dependencies in detached mode using Docker Compose.

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

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

### Account Creation Success Handling

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Processes a successful account creation response, logs a success message, and initiates the 2FA setup process.

```javascript
.then(data => { // This block only runs if response.ok was true and response.json() succeeded if (data.success) { accountCreated = true; console.log('Account created successfully. User credentials should be saved to credentials.json'); // Generate 2FA setup - Use the correct endpoint and method fetch('/api/user/2fa/setup', { method: 'POST' })
```

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

### Enforce Dark Mode and Custom Styles

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Applies dark theme and custom background/element colors to the setup page. This ensures a consistent dark mode experience during the initial setup process.

```javascript
document.documentElement.classList.add('dark-theme');
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 NewtArr Version

Source: https://context7.com/elfhosted/newtarr/llms.txt

Fetches the version string of the NewtArr application from the bundled version.txt file.

```bash
curl http://localhost:9705/version.txt
```

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

### Keyboard Event Listener for Navigation

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Listens for the 'Enter' key press to trigger navigation through the setup steps, providing an alternative to clicking buttons. It checks the current step to determine the correct action.

```javascript
document.addEventListener('keydown', function(e) { if (e.key === 'Enter') { e.preventDefault(); // Prevent form submission if (currentStep === 1 && document.activeElement !== accountNextButton) { accountNextButton.click(); } else if (currentStep === 2 && document.activeElement !== twoFactorNextButton) { twoFactor
```

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

### Update Huntarr.io Manually

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

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

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

### Modern Setup Page Layout (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles the overall login page layout with a gradient background, centering content, and padding. It sets the minimum height to fill the viewport.

```css
/* Modern setup page styles */
.login-page {
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh;
  background: linear-gradient(135deg, #13171f 0%, #1c2230 100%);
  margin: 0;
  padding: 20px;
}
```

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

### Schedule Data Structure Example

Source: https://github.com/elfhosted/newtarr/blob/main/docs/features/scheduling.html

This JSON object represents a single schedule configuration. It includes details like the action to perform, the time and days for execution, the target app, and its enabled status.

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

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

### Update Huntarr.io via Docker

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

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

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

### Display 2FA QR Code and Secret

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Handles the response from the 2FA setup API. If successful, it updates the QR code image source and displays the secret key. Includes fallback for updating the DOM.

```javascript
.then(twoFactorData => { if (twoFactorData.success) { // Use the correct property 'qr_code_url' and set the img src directly const qrCodeImg = qrCodeElement.querySelector('img'); // Find the img tag within the div if (qrCodeImg) { qrCodeImg.src = twoFactorData.qr_code_url; // Set src directly qrCodeImg.style.display = 'block'; // Ensure it's visible } else { // Fallback if img tag wasn't there initially qrCodeElement.innerHTML = `<img src="${twoFactorData.qr_code_url}" alt="QR Code" style="display: block; max-width: 100%; height: auto;">`; } secretKeyElement.textContent = twoFactorData.secret; showStep(2); } else { // Use .error if available, otherwise provide a default showError('Failed to generate 2FA setup: ' + (twoFactorData.error || 'Unknown error')); } })
```

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

### Get Hourly API Usage Caps

Source: https://context7.com/elfhosted/newtarr/llms.txt

Retrieves current per-app API usage counts and their configured limits for the current hour.

```bash
curl http://localhost:9705/api/hourly-caps
```

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

### Get Hourly API Caps

Source: https://context7.com/elfhosted/newtarr/llms.txt

Returns current per-app API usage counts and their configured limits for the current hour.

```APIDOC
## GET /api/hourly-caps

### Description
Returns current per-app API usage counts and their configured limits for the current hour.

### Method
GET

### Endpoint
/api/hourly-caps

### Request Example
```bash
curl http://localhost:9705/api/hourly-caps
```

### Response
#### Success Response (200)
- **caps** (object) - Current API usage counts for each application.
  - **app_type** (integer) - The number of API calls made by the application in the current hour.
- **limits** (object) - The configured API limits for each application.
  - **app_type** (integer) - The maximum number of API calls allowed for the application in the current hour.

### Response Example
```json
{
  "success": true,
  "caps": {
    "sonarr": 14,
    "radarr": 7,
    "lidarr": 0,
    "readarr": 0,
    "whisparr": 0,
    "eros": 0
  },
  "limits": {
    "sonarr": 20,
    "radarr": 20,
    "lidarr": 20,
    "readarr": 20,
    "whisparr": 20,
    "eros": 20
  }
}
```
```

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

### Settings Management with settings_manager

Source: https://context7.com/elfhosted/newtarr/llms.txt

Manage NewtArr application settings using the `settings_manager` module. Load, get, and save settings for various *arr applications and global configurations. Settings are cached in memory for 5 seconds.

```python
from src.primary import settings_manager

# Load all settings for a specific app (uses 5-second in-memory cache)
sonarr_cfg = settings_manager.load_settings("sonarr")
print(sonarr_cfg)
# {
#   "instances": [{"name": "Default", "api_url": "http://sonarr:8989", "api_key": "abc123", "enabled": true}],
#   "hunt_missing_items": 1,
#   "hunt_upgrade_items": 0,
#   "hunt_missing_mode": "episodes",   # "episodes" | "seasons_packs" | "shows"
#   "upgrade_mode": "episodes",
#   "sleep_duration": 900,
#   "monitored_only": true,
#   "skip_future_episodes": true,
#   "hourly_cap": 20
# }

# Read a single key with a default fallback
api_url = settings_manager.get_setting("sonarr", "api_url", "")

# Save mutated settings back to disk (clears the cache for this app)
sonarr_cfg["hunt_missing_items"] = 5
settings_manager.save_settings("sonarr", sonarr_cfg)

# Read an advanced/global setting from general.json
api_timeout = settings_manager.get_advanced_setting("api_timeout", 120)
ssl_verify  = settings_manager.get_advanced_setting("ssl_verify", True)

# List apps that have a valid api_url + api_key configured
configured = settings_manager.get_configured_apps()
# Returns: ["sonarr", "radarr"]

# Load settings for every known app type at once
all_cfg = settings_manager.get_all_settings()

# Force-clear the in-memory cache (e.g., after an external file change)
settings_manager.clear_cache("sonarr")   # single app
settings_manager.clear_cache()           # all apps

```

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

### Start and Manage NewtArr Background Threads

Source: https://context7.com/elfhosted/newtarr/llms.txt

Initiates the main background processing thread for NewtArr. This function blocks until a stop event is set, allowing for graceful shutdown. It also shows how to trigger an immediate cycle reset for a specific app and how to signal a shutdown.

```python
# src/primary/background.py — internal lifecycle (not called directly by end-users)

# 1. Application startup (called from main.py in a daemon thread)
from src.primary.background import start_huntarr, stop_event

# start_huntarr() blocks until stop_event is set
import threading
bg = threading.Thread(target=start_huntarr, daemon=True)
bg.start()

# 2. Trigger an immediate cycle reset for an app (skips remaining sleep)
from src.primary.background import reset_app_cycle
reset_app_cycle("sonarr")  # writes /config/reset/sonarr.reset
# The sonarr thread detects the file within 1 second and restarts the cycle

# 3. Signal a graceful shutdown
stop_event.set()   # all per-app threads exit their loops within seconds
bg.join(timeout=10)
```

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

### Manage Scheduler Engine

Source: https://context7.com/elfhosted/newtarr/llms.txt

Start, stop, and retrieve execution history for the scheduler engine. The scheduler checks the schedule.json file every 60 seconds to execute configured actions for apps.

```python
from src.primary.scheduler_engine import (
    start_scheduler,
    stop_scheduler,
    get_execution_history,
    load_schedule,
)

# Start the scheduler background thread (called by start_huntarr automatically)
start_scheduler()

# Example schedule.json structure
schedule = {
    "global": [
        {
            "id": "nightly-pause",
            "action": "disable",        # "enable" | "disable" | "api-5" | "api-20"
            "app": "global",
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "hour": 2,
            "minute": 0,
            "enabled": True
        },
        {
            "id": "morning-resume",
            "action": "enable",
            "app": "global",
            "days": [],                 # empty = every day
            "hour": 7,
            "minute": 0,
            "enabled": True
        }
    ],
    "sonarr": [
        {
            "id": "rate-limit-peak",
            "action": "api-5",          # set hourly cap to 5 during peak hours
            "app": "sonarr",
            "days": ["saturday", "sunday"],
            "hour": 20,
            "minute": 0,
            "enabled": True
        }
    ]
}

# Retrieve the last 50 scheduler execution history entries
history = get_execution_history()
for entry in history[:3]:
    print(entry)
# {'timestamp': '2026-02-24 07:00:01', 'id': 'morning-resume',
#  'action': 'enable', 'app': 'global', 'status': 'success',
#  'message': 'All apps enabled successfully'}

# Stop the scheduler gracefully
stop_scheduler()
```

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

### Serve Documentation Locally with Python

Source: https://github.com/elfhosted/newtarr/blob/main/docs/README.md

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

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

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

### Get App Statistics

Source: https://context7.com/elfhosted/newtarr/llms.txt

Returns counters for each app. JWT is required in full-auth deployments.

```APIDOC
## GET /api/stats

### Description
Returns counters for each app (e.g., hunted, upgraded).

### Method
GET

### Endpoint
/api/stats

### Request Example
```bash
curl http://localhost:9705/api/stats
```

### Response
#### Success Response (200)
- **stats** (object) - An object containing statistics for each application.
  - **app_type** (object) - Statistics for a specific app.
    - **hunted** (integer) - Number of items hunted.
    - **upgraded** (integer) - Number of items upgraded.

### Response Example
```json
{
  "success": true,
  "stats": {
    "sonarr": {"hunted": 142, "upgraded": 17},
    "radarr": {"hunted": 58,  "upgraded": 4},
    "lidarr": {"hunted": 9,   "upgraded": 0}
  }
}
```
```

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

### Handle Account Creation

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Handles the click event for the account creation 'Next' button. It validates username, password, and confirmation password, then sends a POST request to the backend to create the account. It also handles existing accounts by simply proceeding to the next step.

```javascript
accountNextButton.addEventListener('click', function() { const username = usernameInput.value.trim(); // Trim whitespace const password = passwordInput.value; const confirmPassword = confirmPasswordInput.value; // No longer needed here - will be captured in step 3 if (!username || !password || !confirmPassword) { showError('All fields are required'); return; } // Add username length validation if (username.length < 3) { showError('Username must be at least 3 characters long'); return; } if (password !== confirmPassword) { showError('Passwords do not match'); return; } // Validate password complexity const passwordError = validatePassword(password); if (passwordError) { showError(passwordError); return; } // Store user data userData.username = username; userData.password = password; if (accountCreated) { // If account already created, just move to next step showStep(2); return; } // Create user account with improved error handling fetch('/setup', { // Corrected endpoint from /api/setup to /setup method: 'POST', redirect: 'error', // Add this line to prevent following redirects headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: username, password: password, confirm_password: confirmPassword // Keep confirm_password if backend expects it, otherwise remove }) }) .then(response => { // Check if response is ok before parsing JSON if (!response.ok) { // Check content type to see if it's likely JSON const contentType = response.headers.get("content-type"); if (contentType && contentType.indexOf("application/json") !== -1) { return response.json().then(data => { throw new Error(data.error || 'An unknown error occurred'); }); } else { return response.text().then(text => { throw new Error(text || 'An unknown error occurred'); }); } } return response.json(); }) .then(data => { // Assuming successful creation returns some data, e.g., { success: true } accountCreated = true; showStep(2); // Move to the next step (2FA setup) }) .catch(error => { showError(error.message); }); });
```

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

### Get Application Statistics

Source: https://context7.com/elfhosted/newtarr/llms.txt

Retrieves current counters for each *arr application. JWT is required in full-auth deployments.

```bash
curl http://localhost:9705/api/stats
```

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

### Fetch and Display Version

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/topbar.html

JavaScript code to fetch the application version from 'version.txt' and display it in an element with the ID 'version-value'. Includes basic error handling.

```javascript
document.addEventListener('DOMContentLoaded', function() { var el = document.getElementById('version-value'); if (el) { fetch('/version.txt').then(function(r) { return r.text(); }) .then(function(v) { el.textContent = v.trim(); }) .catch(function() {}); } });
```

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

### Huntarr.io Docker Compose Configuration

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

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

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

### Navigate to Huntarr.io Directory

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

```bash
cd Huntarr.io
```

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

### Login Container Styling (CSS)

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/setup.html

Styles the main container for the login/setup interface. It sets a fixed width, gradient background, rounded corners, shadow, and a subtle border.

```css
.login-container {
  width: 625px; /* Increased by 25% */
  max-width: 90%;
  background: linear-gradient(180deg, rgba(22, 26, 34, 0.98), rgba(18, 22, 30, 0.95));
  border-radius: 15px;
  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.3);
  overflow: hidden;
  border: 1px solid rgba(90, 109, 137, 0.15);
}
```

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

### Scheduler REST API: Get Execution History

Source: https://context7.com/elfhosted/newtarr/llms.txt

Retrieve the last 50 scheduler execution history entries. This endpoint provides a log of past scheduler actions and their outcomes.

```bash
# GET /api/scheduler/history — retrieve scheduler execution history (last 50 entries)
curl http://localhost:9705/api/scheduler/history
# {"success": true, "history": [...], "timestamp": "2026-02-24T07:00:01"}
```

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

### Initialize Dark Mode and Set Theme

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/user.html

Initializes dark mode on page load and persists the setting in local storage. It also sends a POST request to update the server's theme setting.

```javascript
document.addEventListener('DOMContentLoaded', function() {
  // Apply dark theme
  document.body.classList.add('dark-theme');
  localStorage.setItem('huntarr-dark-mode', 'true');

  // Update server setting to dark mode
  fetch('/api/settings/theme', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ dark_mode: true })
  }).catch(error => console.error('Error saving theme:', error));
});
```

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

### View Huntarr.io Logs (Docker)

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Access the logs for the Huntarr.io container to troubleshoot issues when running via Docker.

```bash
docker logs huntarr
```

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

### Clone Huntarr.io Repository

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

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

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

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

### Access Huntarr.io Web Interface

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Open your web browser and navigate to this address to access the Huntarr.io interface.

```bash
http://localhost:7575
```

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

### App Panels and Additional Options Styling

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/apps_section.html

Styles the app panels and additional options sections to ensure proper spacing and visibility, especially for content at the bottom of the screen.

```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;
}
```

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

### Link to Huntarr.io Documentation Page

Source: https://github.com/elfhosted/newtarr/blob/main/docs/settings/index.html

Use this HTML snippet to create an information icon link to specific Huntarr.io documentation pages. Adjust the href attribute to point to the desired documentation URL.

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

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

### Process Stalled Downloads with Swaparr

Source: https://context7.com/elfhosted/newtarr/llms.txt

Use this function to monitor and manage stalled downloads for various arr applications. Configure settings like max strikes, download time limits, and whether to remove items from the download client. Ensure Swaparr is enabled in its configuration file.

```python
from src.primary.apps.swaparr.handler import process_stalled_downloads
from src.primary import settings_manager

# Swaparr must be enabled in /config/swaparr.json
swaparr_cfg = {
    "enabled": True,
    "max_strikes": 3,
    "max_download_time": "2h",      # "30m", "2h", "1d"
    "ignore_above_size": "25GB",    # skip files larger than this
    "remove_from_client": True,     # also remove from the download client
    "dry_run": False                # set True to log actions without deleting
}

# Typical sonarr instance settings (as built by background.py)
sonarr_instance = {
    "instance_name": "Default",
    "api_url": "http://sonarr:8989",
    "api_key": "abc123abc123",
    "api_timeout": 120
}

# Run Swaparr against the Sonarr instance
process_stalled_downloads("sonarr", sonarr_instance, swaparr_cfg)
# Logs stalled items, applies strikes, removes items at max_strikes

# Supported app names: "sonarr", "radarr", "lidarr", "readarr", "whisparr"
process_stalled_downloads("radarr", {
    "instance_name": "4K Movies",
    "api_url": "http://radarr4k:7878",
    "api_key": "xyz789xyz789",
    "api_timeout": 120
}, swaparr_cfg)
```

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

### Docker Compose for NewtArr Deployment

Source: https://context7.com/elfhosted/newtarr/llms.txt

Deploy NewtArr using Docker Compose, mapping the necessary port and volume for configuration persistence.

```yaml
# docker-compose.yml
services:
  newtarr:
    image: ghcr.io/elfhosted/newtarr:latest
    container_name: newtarr
    restart: always
    ports:
      - "9705:9705"
    volumes:
      - ./config:/config
    environment:
      - TZ=UTC

# Access the web UI at http://localhost:9705
# All settings are stored in ./config/*.json

```

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

### Check if Huntarr.io Service is Running (Docker)

Source: https://github.com/elfhosted/newtarr/blob/main/docs/getting-started/installation.html

Use this command to verify if the Huntarr.io container is active when using Docker.

```bash
docker ps | grep huntarr
```

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

### Apps Container Styling

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/apps_section.html

Sets the height and flex properties for the apps container to manage its layout within the overall application structure.

```css
/* Apps container styling */
#appsContainer {
  height: auto;
  flex: 1;
  overflow: visible;
}
```

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

### Navigation Menu Styling

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/sidebar.html

Styles the main navigation menu container, setting it to display as a column and defining padding.

```css
.nav-menu {
  display: flex;
  flex-direction: column;
  padding: 5px 0 20px 0;
  flex-grow: 1;
}
```

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

### Run NewtArr with Docker Compose

Source: https://github.com/elfhosted/newtarr/blob/main/README.md

This Docker Compose configuration sets up NewtArr with persistent storage and automatic restarts. The web UI is accessible on port 9705.

```yaml
services:
  newtarr:
    image: ghcr.io/elfhosted/newtarr:latest
    container_name: newtarr
    restart: always
    ports:
      - "9705:9705"
    volumes:
      - ./config:/config
    environment:
      - TZ=UTC
```

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

### Generate Time Options in Jinja2

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/scheduling_section.html

Generates hour and minute options for a time selector using Jinja2 templating. Use this to create dropdowns for scheduling.

```html
{% for h in range(0, 24) %} {{ '%02d' % h }} {% endfor %} : {% for m in range(0, 60, 5) %} {{ '%02d' % m }} {% endfor %}
```

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

### Swaparr — Stalled Download Handler

Source: https://context7.com/elfhosted/newtarr/llms.txt

Swaparr monitors download queues for stalled or problematic downloads across various *arr applications. It tracks items with strikes for conditions like metadata errors or zero progress, and can delete them from the queue and optionally from the download client upon reaching a maximum strike count. Previously removed items are tracked for 30 days.

```APIDOC
## Swaparr — Stalled Download Handler

Swaparr monitors every *arr app's download queue for stalled or problematic downloads. Items accumulate "strikes" (configurable max, default 3) for conditions such as a metadata error, an ETA exceeding the configured maximum, or zero download progress while not queued. When max strikes are reached the item is deleted from the queue (and optionally from the download client). Previously removed items are tracked for 30 days to handle reappearances.

```python
from src.primary.apps.swaparr.handler import process_stalled_downloads
from src.primary import settings_manager

# Swaparr must be enabled in /config/swaparr.json
swaparr_cfg = {
    "enabled": True,
    "max_strikes": 3,
    "max_download_time": "2h",      # "30m", "2h", "1d"
    "ignore_above_size": "25GB",    # skip files larger than this
    "remove_from_client": True,     # also remove from the download client
    "dry_run": False                # set True to log actions without deleting
}

# Typical sonarr instance settings (as built by background.py)
sonarr_instance = {
    "instance_name": "Default",
    "api_url": "http://sonarr:8989",
    "api_key": "abc123abc123",
    "api_timeout": 120
}

# Run Swaparr against the Sonarr instance
process_stalled_downloads("sonarr", sonarr_instance, swaparr_cfg)
# Logs stalled items, applies strikes, removes items at max_strikes

# Supported app names: "sonarr", "radarr", "lidarr", "readarr", "whisparr"
process_stalled_downloads("radarr", {
    "instance_name": "4K Movies",
    "api_url": "http://radarr4k:7878",
    "api_key": "xyz789xyz789",
    "api_timeout": 120
}, swaparr_cfg)
```
```

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

### Scheduler REST API: Load Schedules

Source: https://context7.com/elfhosted/newtarr/llms.txt

Retrieve all current scheduler configurations. This endpoint is useful for viewing the existing schedule settings.

```bash
# GET /api/scheduler/load — retrieve all schedules
curl http://localhost:9705/api/scheduler/load
# {"global": [], "sonarr": [], "radarr": [], "lidarr": [], "readarr": []}
```

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

### CSS for Day Selection

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/scheduling_section.html

Styles the checkboxes for selecting days of the week, using a responsive grid layout.

```css
/* Day Selection */
.days-selection {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
  gap: 10px;
}

.day-checkbox {
  display: flex;
  align-items: center;
}

.day-checkbox label {
  margin-left: 8px;
  margin-bottom: 0;
  cursor: pointer;
}

.day-input {
  width: 16px;
  height: 16px;
}
```

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

### CSS for Time Selection

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/scheduling_section.html

Styles the time input fields and separators for time selection.

```css
/* Time Selection */
.time-selection {
  display: flex;
  align-items: center;
  gap: 8px;
}

.time-selection .form-control {
  width: 80px;
}

.time-separator {
  font-weight: bold;
  color: var(--text-primary, #fff);
}
```

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

### Version Bar Styling CSS

Source: https://github.com/elfhosted/newtarr/blob/main/frontend/templates/components/topbar.html

Styles the bar that displays version information. It includes styling for individual version items, dividers, and links.

```css
.version-bar {
  display: flex;
  align-items: center;
  gap: 8px;
  white-space: nowrap;
  background: rgba(20, 30, 45, 0.4);
  border-radius: 6px;
  padding: 4px 10px;
  box-shadow: inset 0 0 5px rgba(0, 0, 0, 0.2);
  border: 1px solid rgba(90, 109, 137, 0.15);
}
.version-item {
  display: flex;
  align-items: center;
  gap: 4px;
  font-size: 12px;
  color: #e0e6ed;
  transition: all 0.2s ease;
}
.version-item:hover {
  transform: translateY(-1px);
}
.version-divider {
  width: 1px;
  height: 14px;
  background-color: rgba(120, 140, 180, 0.3);
}
.version-icon {
  color: #8D9E40;
  font-size: 13px;
  filter: drop-shadow(0 0 2px rgba(80, 118, 46, 0.4));
}
.star-icon {
  color: #ffd700;
  animation: star-pulse 3s infinite alternate;
}
@keyframes star-pulse {
  0% {
    filter: drop-shadow(0 0 2px rgba(255, 215, 0, 0.4));
  }
  100% {
    filter: drop-shadow(0 0 5px rgba(255, 215, 0, 0.8));
  }
}
.version-bar a {
  color: #8D9E40;
  text-decoration: none;
  font-weight: 600;
  transition: all 0.2s ease;
  position: relative;
}
.version-bar a::after {
  content: '';
  position: absolute;
  width: 0;
  height: 1px;
  bottom: -1px;
  left: 0;
  background-color: #8D9E40;
  transition: width 0.3s ease;
}
.version-bar a:hover {
  color: #a8b84d;
}
.version-bar a:hover::after {
  width: 100%;
}
.developer-credit {
  color: #e0e6ed;
}
.developer-credit a {
  color: #8D9E40;
  font-weight: 600;
}
```