Reference¶

Quick reference documentation for qBitrr commands, APIs, and specifications.

Command Line Interface¶

Complete CLI reference for qBitrr command-line options.

Basic Usage¶

# Start qBitrr with default config
qbitrr

# Generate default configuration
qbitrr --gen-config

# Show version information
qbitrr --version

# Show license information
qbitrr --license

# Show source code link
qbitrr --source

# Show help message
qbitrr --help

Note: qBitrr uses configuration files and environment variables for all settings. There are no CLI flags for database operations, debugging, or service management. Use systemd, Docker, or process managers for service control.

Environment Variables¶

qBitrr supports extensive environment variable configuration:

Core Settings¶

qBittorrent Settings¶

Arr Instance Settings¶

For each Arr type, you can set:

WebUI Settings¶

Docker-Specific¶

Usage Examples¶

Basic Startup¶

# Default startup
qbitrr

# With custom config
qbitrr --config /custom/config.toml

# With debug logging
export QBITRR_LOG_LEVEL=DEBUG
qbitrr

Docker Environment¶

# Run with environment variables
docker run -d \
  -e QBITRR_LOG_LEVEL=DEBUG \
  -e QBITRR_QBITTORRENT_HOST=http://qbittorrent:8080 \
  -e QBITRR_RADARR_URL=http://radarr:7878 \
  -e QBITRR_RADARR_API_KEY=your-key \
  -v /config:/config \
  feramance/qbitrr:latest

Database Maintenance¶

# Check database health
qbitrr --validate-db

# If corruption detected, repair
qbitrr --repair-db

# Optimize database
qbitrr --vacuum-db

# Reset search state (useful after config changes)
qbitrr --reset-searches

Debugging¶

# Test configuration without starting
qbitrr --validate-config
qbitrr --test-connections

# Run once and exit (for testing event loop)
qbitrr --once --debug

# Dry run (see what would happen without making changes)
qbitrr --dry-run

Systemd Service¶

# Check if running
systemctl status qbitrr

# View logs
journalctl -u qbitrr -f

# Restart service
systemctl restart qbitrr

Exit Codes¶

qBitrr uses standard exit codes to indicate success or failure:

Configuration File Priority¶

qBitrr searches for configuration in this order:

1. Command-line argument: --config /path/to/config.toml
2. Environment variable: QBITRR_CONFIG=/path/to/config.toml
3. Docker default: /config/config.toml (if running in Docker)
4. User config: ~/.config/qBitrr/config.toml (pip install)
5. Local config: ~/config/config.toml (native install)

Logging Levels¶

Control log verbosity with QBITRR_LOG_LEVEL or --debug:

Examples:

# Debug mode
qbitrr --debug

# Or via environment
export QBITRR_LOG_LEVEL=DEBUG
qbitrr

# Or in config.toml
[Settings]
LogLevel = "DEBUG"

API Reference¶

REST API Endpoints¶

The qBitrr WebUI is powered by a REST API:

Process Management¶

GET /api/processes

{
  "processes": [
    {
      "name": "Radarr-Main",
      "status": "running",
      "pid": 12345,
      "uptime": 3600
    }
  ]
}

Logs¶

GET /api/logs?limit=100&level=INFO

{
  "logs": [
    {
      "timestamp": "2025-11-26T12:00:00Z",
      "level": "INFO",
      "message": "Torrent imported successfully",
      "source": "Radarr-Main"
    }
  ]
}

Radarr Movies¶

GET /api/radarr/movies?instance=Radarr-Main

{
  "movies": [
    {
      "id": 1,
      "title": "Example Movie",
      "year": 2024,
      "monitored": true,
      "hasFile": true
    }
  ]
}

Configuration¶

GET /api/config
POST /api/config

Authentication¶

If WebUI token is configured:

curl http://localhost:6969/api/processes \
  -H "X-API-Token: your-token-here"

Configuration Schema¶

Main Settings¶

[Settings]
LogLevel = "INFO"           # DEBUG | INFO | WARNING | ERROR | CRITICAL
CheckInterval = 60          # Seconds between torrent checks
MaxConcurrentChecks = 10    # Max parallel health checks
RetentionDays = 30          # Days to keep old data
WebUIPort = 6969            # WebUI port
[WebUI]
Host = "0.0.0.0"            # WebUI bind address
Token = ""                  # Optional API token

qBittorrent¶

[qBit]
Host = "localhost"          # qBittorrent URL
Port = 8080                 # qBittorrent port
UserName = "admin"          # qBit username
Password = "adminadmin"     # qBit password

Arr Instances¶

[[Radarr]]  # or [[Sonarr]] or [[Lidarr]]
Name = "Radarr-Main"        # Unique identifier
URI = "http://localhost:7878"
APIKey = "your-api-key"
Category = "radarr"         # qBit category
AutoStart = true            # Start on launch
HealthCheck = true          # Enable health monitoring
InstantImport = true        # Instant imports
SearchMissing = false       # Auto-search missing
SearchPeriodDays = 7        # Search interval

File Locations¶

Default Paths¶

Log Files¶

• Main.log - qBitrr application logs
• WebUI.log - Web interface logs
• {ArrName}.log - Per-Arr instance logs

Error Codes¶

Common Exit Codes¶

HTTP Status Codes¶

Database Schema¶

Tables¶

downloads¶

Tracks downloaded torrents:

CREATE TABLE downloads (
  id INTEGER PRIMARY KEY,
  hash TEXT UNIQUE NOT NULL,
  name TEXT,
  arr_instance TEXT,
  status TEXT,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);

searches¶

Search activity history:

CREATE TABLE searches (
  id INTEGER PRIMARY KEY,
  arr_instance TEXT,
  media_id INTEGER,
  search_type TEXT,
  created_at TIMESTAMP
);

expiry¶

Entry expiration tracking:

CREATE TABLE expiry (
  id INTEGER PRIMARY KEY,
  entry_type TEXT,
  entry_id INTEGER,
  expires_at TIMESTAMP
);

Glossary¶

Comprehensive glossary of qBitrr and related terminology.

qBitrr Terminology¶

Torrent Terminology¶

Media Terminology¶

Arr-Specific Terms¶

Technical Terms¶

Status Terms¶

For more detailed definitions, see the Complete Glossary.

Quick Reference Tables¶

Common Configuration Values¶

Log Levels¶

Import Modes¶

Seeding Modes (RemoveTorrent)¶

Search Ordering¶

Default Port Numbers¶

File Size Units¶

qBitrr accepts these file size units:

Example:

[Settings]
FreeSpace = "50G"  # 50 gigabytes

Time Units¶

qBitrr uses seconds for time values. Common conversions:

Example:

[Radarr.Torrent]
MaximumETA = 86400  # 24 hours
StalledDelay = 30   # 30 seconds

[Radarr.Torrent.SeedingMode]
MaxSeedingTime = 604800  # 7 days

API Response Formats¶

All qBitrr API endpoints return JSON with this structure:

Success:

{
  "status": "success",
  "data": {
    // Response data here
  }
}

Error:

{
  "status": "error",
  "error": "Error message description",
  "code": 400
}

Cron Expression Examples¶

For scheduled tasks (auto-updates, etc.):

Configuration Examples¶

Minimal Configuration¶

Simplest possible setup:

[Settings.Qbittorrent]
Host = "http://localhost"
Port = 8080
Username = "admin"
Password = "adminadmin"

[[Radarr]]
Name = "Radarr"
URI = "http://localhost:7878"
APIKey = "your-api-key-here"

Production Configuration¶

Recommended production settings:

[Settings]
LogLevel = "INFO"
FreeSpace = "50G"
AutoPauseResume = true

[qBit]
Host = "qbittorrent"
Port = 8080
UserName = "admin"
Password = "your-secure-password"

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = "your-secret-token-here"

[[Radarr]]
Name = "Radarr-Movies"
URI = "http://radarr:7878"
APIKey = "${RADARR_API_KEY}"
Category = "radarr"
importMode = "Auto"

[Radarr-Movies.EntrySearch]
SearchMissing = true
SearchRequestsEvery = 300
DoUpgradeSearch = true

[Radarr-Movies.Torrent]
MaximumETA = 86400
StalledDelay = 30
DoNotRemoveSlow = true

[Radarr-Movies.Torrent.SeedingMode]
MaxUploadRatio = 2.0
MaxSeedingTime = 604800
RemoveTorrent = 3

Complete Configuration¶

See Configuration File Reference for comprehensive examples.

Version Compatibility¶

qBittorrent¶

• v4.x - Fully supported (automatically detected)
• v5.x - Fully supported (automatically detected)

Arr Applications¶

• Radarr - v3.x, v4.x, v5.x
• Sonarr - v3.x, v4.x
• Lidarr - v1.x, v2.x

Python¶

• Minimum - Python 3.11
• Recommended - Python 3.12+

Useful Links¶

• Repository: https://github.com/Feramance/qBitrr
• PyPI: https://pypi.org/project/qBitrr2/
• Docker Hub: https://hub.docker.com/r/feramance/qbitrr
• Documentation: https://feramance.github.io/qBitrr/
• Issues: https://github.com/Feramance/qBitrr/issues
• Discussions: https://github.com/Feramance/qBitrr/discussions

Related Documentation¶

• Configuration Guide
• Troubleshooting
• FAQ
• Development

Support¶

Need help? Check out:

• FAQ - Common questions
• Troubleshooting - Problem solving
• GitHub Discussions - Community support