Skip to Content
DocsCLI Referencesoftware

qb software - Version Checking Utility

Software Version Utility

Query upstream APIs and refresh dashboard version inventory

The qb software check utility queries upstream release APIs for every installed application, compares versions against what’s currently deployed, and writes JSON files the dashboard consumes for update notifications.

For Application Management

This utility is for version checking only. To install, update, remove, or reinstall applications:

qb install <app> -u username
qb update <app> -u username
qb reinstall <app> -u username
qb remove <app> -u username

See the Applications documentation for complete workflows.

Quick Reference

CommandDescription
qb software check -u usernameRefresh version inventory for a specific user
qb software check --cronRefresh version inventory for all users (used by nightly cron)

What Does It Do?

The software system utility (/opt/quickbox/src/system/software) performs:

  1. Queries the database for all software installed by a given user
  2. Fetches upstream release data from GitHub/vendor APIs for each application
  3. Compares installed version vs. latest available version
  4. Writes JSON files to /srv/quickbox/logs/:
    • username.swCheck.json - Current installed versions
    • username.swUpdate.json - Available updates

The dashboard reads these JSON files to display version badges and update notifications.

Usage

Check Specific User

Refresh version inventory for one user:

qb software check -u username

When to use:

  • After installing new software
  • When dashboard shows stale version info
  • Before running updates to see what’s available
  • Troubleshooting version display issues

Check All Users (Cron Mode)

Refresh version inventory for every user:

qb software check --cron

When to use:

  • Manually trigger the nightly version check
  • After bulk application installations
  • Testing version detection across multiple users

Automated Checks

QuickBox runs qb software check --cron nightly via cron to keep dashboard version information current. Manual runs are typically only needed for immediate updates.

How Version Detection Works

The utility uses the quickbox::software::release::resolve function to query upstream repositories.

GitHub Release Detection

Most applications use GitHub releases:

# Example: Query Sonarr latest version
quickbox::software::release::resolve "Sonarr/Sonarr" version

Process:

  1. Queries GitHub API for latest release tag
  2. Parses version number from tag (e.g., v3.0.10 → 3.0.10)
  3. Compares against installed version from database
  4. If different, writes to update JSON file

Branch-Specific Detection

Some applications support multiple release branches:

# Sonarr supports v3 and v4 branches
quickbox::software::release::resolve "Sonarr/Sonarr" version "v3"
quickbox::software::release::resolve "Sonarr/Sonarr" version "v4"

The utility detects which branch is currently installed and checks the appropriate upstream version.

Application Self-Reporting

Applications like Bazarr write their own version file:

# Read installed version from application
cat "/opt/username/Bazarr/VERSION"

If the self-reported version differs from the database, the utility updates the database entry before checking for upstream updates.

JSON File Structure

Current Versions (username.swCheck.json)

[
  {
    "software_name": "sonarr",
    "software_version": "4.0.2.1312",
    "software_alt_version": ""
  },
  {
    "software_name": "radarr",
    "software_version": "5.3.6.8612",
    "software_alt_version": ""
  }
]

Available Updates (username.swUpdate.json)

[
  {
    "software_name": "sonarr",
    "software_current_version": "4.0.2.1312",
    "software_available_version": "4.0.10.2544"
  }
]

Fields:

  • software_name - Application identifier (matches database)
  • software_version / software_current_version - Currently installed version
  • software_available_version - Latest upstream version
  • software_alt_version - Alternate version info (e.g., nightly builds)

Supported Applications

The version checker supports all QuickBox applications with upstream release tracking:

Media Management

Download Clients

Media Servers

Indexers & Trackers

Media Requests

Automation & Tools

File Management

Utilities & System

See the Applications documentation for installation guides.

Common Workflows

After Installing Software

Refresh the dashboard to show the new application:

qb software check -u john

Check Available Updates

View what updates are available:

# Refresh version data
qb software check -u john
 
# Inspect JSON directly
cat /srv/quickbox/logs/john.swUpdate.json

Troubleshoot Version Display

If dashboard shows incorrect versions:

# Force refresh version inventory
qb software check -u john
 
# Check JSON files
cat /srv/quickbox/logs/john.swCheck.json
cat /srv/quickbox/logs/john.swUpdate.json
 
# Verify database entries
sqlite3 /opt/quickbox/config/db/qbpro.db \
  "SELECT software_name, software_version FROM user_software 
   WHERE user_id = (SELECT id FROM user_information WHERE username = 'john');"

Automated Checks

QuickBox runs automated version checks via cron:

Nightly Cron Job

# Located in: /etc/cron.d/quickbox
qb software check --cron

Schedule:

  • Runs once per day (typically 2-4 AM)
  • Checks all users on the system
  • Updates dashboard version information
  • Logs to system_log table with source=‘cron’

Manual Trigger

Manually run the same check:

qb software check --cron

Troubleshooting

Version Check Not Working

# Check if software utility is present
ls -la /opt/quickbox/src/system/software
 
# Check log files
cat /opt/quickbox/logs/software
 
# Manually refresh for user
qb software check -u username

Dashboard Not Showing Updates

# Verify JSON files exist
ls -la /srv/quickbox/logs/username.sw*.json
 
# Check file permissions
sudo chown www-data:www-data /srv/quickbox/logs/username.sw*.json
 
# Refresh version check
qb software check -u username

Incorrect Versions Displayed

# Compare database vs. JSON files
sqlite3 /opt/quickbox/config/db/qbpro.db \
  "SELECT software_name, software_version FROM user_software 
   WHERE user_id = (SELECT id FROM user_information WHERE username = 'john');"
 
# Check JSON files directly
cat /srv/quickbox/logs/john.swCheck.json
 
# Force version refresh
qb software check -u john
Applications

Install, update, remove, and manage QuickBox applications

Update Command

Update QuickBox core system and applications

Help Command

Display available applications and options

Clean Command

Clean logs and dashboard cache

Need Help?

Join the Community

Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.

Dedicated Support
Feature Previews
Community Configs
Active Discussions
Join Discord Server
newssupport