Getting Started¶

Home > Getting Started

This guide will walk you through setting up AppImage Updater and managing your first applications.

Platform Support: AppImage Updater is designed exclusively for Linux systems, as AppImage is a Linux-specific package format.

Quick Start¶

AppImage Updater automatically creates the configuration directory when you first use any command - no manual initialization is required!

Exploring Commands¶

AppImage Updater provides helpful usage information when you run commands without required arguments:

# See config command help
appimage-updater config

# See show command help
appimage-updater show

# See edit command help
appimage-updater edit

This makes it easy to explore available options and learn the CLI without needing to remember --help flags.

Adding Applications¶

The easiest way to get started is using the add command, which requires minimal input and generates intelligent defaults.

Basic Usage¶

appimage-updater add <app-name> <github-url> <download-directory>

For complete CLI command documentation including all options and examples, see the Usage Guide.

Quick Examples¶

# Add FreeCAD from GitHub
appimage-updater add FreeCAD https://github.com/FreeCAD/FreeCAD ~/Applications/FreeCAD

# Add OrcaSlicer from GitHub
appimage-updater add OrcaSlicer https://github.com/SoftFever/OrcaSlicer ~/Applications/OrcaSlicer

# Add BambuStudio (automatically handles ZIP files)
appimage-updater add BambuStudio https://github.com/bambulab/BambuStudio ~/Applications/BambuStudio

# Add from GitLab repository
appimage-updater add Inkscape https://gitlab.com/inkscape/inkscape ~/Applications/Inkscape

# Add from SourceForge
appimage-updater add MyApp https://sourceforge.net/projects/myapp ~/Applications/MyApp

# Add direct download URL (nightly builds, CI artifacts)
appimage-updater add --direct OrcaSlicer-Nightly https://github.com/SoftFever/OrcaSlicer/releases/download/nightly-builds/OrcaSlicer_Linux_V2.2.0_dev.AppImage ~/Applications/OrcaSlicer

What the `add` Command Does¶

When you run add, it automatically:

Detects repository type automatically - supports GitHub, GitLab, Codeberg, and other Git forges
Detects prerelease requirements - analyzes repositories and auto-enables prerelease for continuous builds
Handles ZIP files automatically - detects and extracts AppImages from ZIP archives (perfect for BambuStudio, etc.)
Selects compatible distributions - automatically chooses the best match for your Linux distribution
Generates smart file patterns based on the repository name
Sets up checksum verification with SHA256 validation
Enables the application immediately
Creates the download directory if needed

Repository Support¶

AppImage Updater supports multiple repository types with intelligent auto-detection:

Supported Repository Types¶

GitHub - https://github.com/user/repo (native support)
GitLab - https://gitlab.com/user/project (GitLab API v4)
Codeberg - https://codeberg.org/user/project (GitHub-compatible API)
Gitea/Forgejo - Self-hosted Git forges with GitHub-compatible APIs
Direct Downloads - Any HTTP/HTTPS URL pointing to AppImage files
Dynamic URLs - URLs that resolve to download links (fallback support)

Automatic Repository Detection¶

AppImage Updater automatically detects the repository type from the URL:

# GitHub (detected automatically)
appimage-updater add FreeCAD https://github.com/FreeCAD/FreeCAD ~/Apps/FreeCAD

# GitLab (detected automatically)
appimage-updater add Inkscape https://gitlab.com/inkscape/inkscape ~/Apps/Inkscape

# SourceForge (detected automatically)
appimage-updater add MyApp https://sourceforge.net/projects/myapp ~/Apps/MyApp

# Self-hosted GitLab (detected via API probing)
appimage-updater add MyApp https://git.company.com/team/project ~/Apps/MyApp

# Direct download (detected automatically)
appimage-updater add --direct MyApp https://example.com/releases/myapp.AppImage ~/Apps/MyApp

Version Pattern Filtering¶

Use --version-pattern to filter releases with regex patterns:

# Only stable releases (exclude prereleases like "1.0-rc1")
appimage-updater add --version-pattern "^[0-9]+\.[0-9]+(\.[0-9]+)?$" MyApp https://github.com/user/repo ~/Apps/MyApp

# Only major.minor versions (exclude patch releases)
appimage-updater add --version-pattern "^[0-9]+\.[0-9]+$" MyApp https://github.com/user/repo ~/Apps/MyApp

# Custom pattern for specific versioning schemes
appimage-updater add --version-pattern "^v[0-9]+\.[0-9]+\.[0-9]+$" MyApp https://github.com/user/repo ~/Apps/MyApp

Smart Prerelease Detection¶

The add command intelligently detects when repositories only provide prerelease versions:

# Continuous build apps are automatically detected
appimage-updater add appimaged https://github.com/probonopd/go-appimage ~/Apps/appimaged
# Output: Auto-detected continuous builds - enabled prerelease support

# Standard release apps keep prerelease disabled
appimage-updater add FreeCAD https://github.com/FreeCAD/FreeCAD ~/Apps/FreeCAD
# No auto-detection message - uses stable releases

How it works:

Continuous builds only → Automatically enables prerelease: true
Stable releases available → Keeps prerelease: false
Your choice matters → --prerelease or --no-prerelease always override detection

Intelligent Distribution Selection¶

When applications provide multiple distribution-specific releases (like BambuStudio's Ubuntu, Fedora variants), AppImage Updater automatically selects the best match for your system:

# BambuStudio example with multiple distributions:
# - BambuStudio_ubuntu-22.04_PR-8017.zip
# - BambuStudio_ubuntu-24.04_PR-8017.zip
# - Bambu_Studio_linux_fedora-v02.02.01.60.AppImage

appimage-updater add BambuStudio https://github.com/bambulab/BambuStudio ~/Apps/BambuStudio
# On Ubuntu 25.04 → Automatically selects ubuntu-24.04 (closest compatible)
# On Fedora 38 → Automatically selects fedora version
# On Gentoo → Shows interactive menu for user selection

Smart Selection Logic:

Perfect Match → Same distribution and version (Score: 100+)
Compatible Family → Ubuntu/Debian, Fedora/CentOS families (Score: 70+)
Version Proximity → Prefers older/same versions for backward compatibility
Interactive Fallback → Unknown distributions get user-friendly selection menu

Non-Interactive Mode: For automation scenarios, disable interactive selection:

appimage-updater check --no-interactive

Advanced Options¶

You can customize the setup with additional options:

# Enable rotation with symlink management
appimage-updater add --rotation --symlink ~/bin/myapp.AppImage --retain 5 MyApp https://github.com/user/repo ~/Apps/MyApp

# Include prerelease versions
appimage-updater add --prerelease NightlyApp https://github.com/user/repo ~/Apps/NightlyApp

# Filter versions with regex patterns (exclude prereleases)
appimage-updater add --version-pattern "^[0-9]+\.[0-9]+$" MyApp https://github.com/user/repo ~/Apps/MyApp

# Add from non-GitHub repositories (GitLab, Codeberg, etc.)
appimage-updater add MyApp https://gitlab.com/user/project ~/Apps/MyApp
appimage-updater add MyApp https://codeberg.org/user/project ~/Apps/MyApp

Checking for Updates¶

For complete command documentation, see the Usage Guide.

Basic Commands¶

# Check all applications
appimage-updater check

# Check without downloading (dry run)
appimage-updater check --dry-run

# Check specific application
appimage-updater check FreeCAD

Debug Mode¶

For troubleshooting, enable debug logging:

appimage-updater --debug check --dry-run

Version Information¶

Check your AppImage Updater version:

appimage-updater --version
# or
appimage-updater -V

Managing Applications¶

List All Applications¶

# List all applications
appimage-updater list

# List in different formats
appimage-updater list --format json   # JSON output for scripting
appimage-updater list --format plain  # Plain text output
appimage-updater list --format html   # HTML output

Show Application Details¶

# Show application details
appimage-updater show FreeCAD

# Show in JSON format (useful for scripting)
appimage-updater show FreeCAD --format json

# Show the add command to recreate the configuration
appimage-updater show FreeCAD --add-command

This displays comprehensive information including:

Configuration settings
Current files in download directory
Detected symlinks
Current version information

Examine Repository Information¶

The repository command provides detailed information about releases and assets available in the configured repositories:

# Show release information for an application
appimage-updater repository OrcaSlicer

# Show detailed asset information
appimage-updater repository OrcaSlicer --assets

# Limit number of releases shown (default: 10)
appimage-updater repository OrcaSlicer --limit 5

# Use glob patterns to examine multiple apps
appimage-updater repository "Orca*" --assets

# Combined options for detailed inspection
appimage-updater repository FreeCAD --limit 3 --assets

This command is useful for:

Troubleshooting - Understanding what releases and assets are available
Pattern Development - Seeing actual filenames to create better patterns
Version Analysis - Checking release dates and version numbering
Asset Discovery - Finding checksums, signatures, and alternative downloads

Edit Application Settings¶

The edit command allows you to modify any configuration setting:

# Enable prereleases
appimage-updater edit GitHubDesktop --prerelease

# Add rotation with symlink
appimage-updater edit MyApp --rotation --symlink ~/bin/myapp.AppImage

# Change download location
appimage-updater edit FreeCAD --download-dir ~/NewLocation/FreeCAD

# Update URL without validation (for direct downloads)
appimage-updater edit MyApp --url https://direct-download-url.com/file.AppImage --force

# Convert existing app to use direct download
appimage-updater edit OrcaSlicer --direct --url https://github.com/SoftFever/OrcaSlicer/releases/download/nightly-builds/OrcaSlicer_Linux_V2.2.0_dev.AppImage

Rotation for Stable Application Access¶

Rotation maintains stable access to your AppImages while keeping previous versions for rollback. See the detailed Rotation Guide for complete information.

Rotation Quick Start¶

# Add an application with rotation enabled
appimage-updater add --rotation --symlink ~/bin/freecad.AppImage FreeCAD https://github.com/FreeCAD/FreeCAD ~/Applications/FreeCAD

This creates a stable symlink at ~/bin/freecad.AppImage that always points to the current version, with automatic rotation when updates are downloaded.

Managing Rotation¶

# Enable rotation for existing application
appimage-updater edit MyApp --rotation --symlink ~/bin/myapp.AppImage

# Set how many old versions to keep (default: 3)
appimage-updater edit MyApp --retain-count 5

# Disable rotation
appimage-updater edit MyApp --no-rotation

For detailed setup, desktop integration, and troubleshooting, see the Rotation Guide.

Multi-App Operations¶

AppImage Updater supports operating on multiple applications simultaneously using app names, lists, or glob patterns.

Multiple App Names¶

# Check specific applications
appimage-updater check FreeCAD VSCode OrcaSlicer

# Show details for multiple apps
appimage-updater show App1 App2 App3

# Edit multiple applications at once
appimage-updater edit FreeCAD VSCode --enable

# Remove multiple applications
appimage-updater remove OldApp1 OldApp2 --force

Glob Patterns¶

Use glob patterns to match multiple applications by name:

# Check all applications starting with "Orca"
appimage-updater check "Orca*"

# Show all applications ending with "Studio"
appimage-updater show "*Studio"

# Disable all test applications
appimage-updater edit "Test*" --disable

# Remove all deprecated applications
appimage-updater remove "Deprecated*" --force

Case-Insensitive Matching¶

All app name matching is case-insensitive:

# These are equivalent
appimage-updater show freecad
appimage-updater show FreeCAD
appimage-updater show FREECAD

Quick Reference¶

Essential Commands¶

For complete command documentation including all options and examples, see the Usage Guide.

Command	Purpose
`appimage-updater add`	Add new application (creates config automatically)
`appimage-updater list`	List all applications
`appimage-updater check [apps...]`	Check for updates (all or specific apps)
`appimage-updater show <apps...>`	Show app details (supports multiple apps)
`appimage-updater edit <apps...>`	Edit app settings (supports multiple apps)
`appimage-updater remove <apps...>`	Remove applications (supports multiple apps)
`appimage-updater repository <apps...>`	Examine repository information and releases
`appimage-updater config`	Manage global configuration settings

Common Options¶

Option	Purpose
`--prerelease`	Include prerelease versions
`--rotation --symlink <path>`	Enable rotation with symlink
`--dry-run`	Preview changes without applying them
`--format <type>`	Output format: rich, plain, json, or html
`--verbose`	Show detailed parameter information
`--yes`	Auto-confirm prompts
`--debug`	Enable debug logging
`--direct`	Treat URL as direct download link

File Locations¶

Path	Purpose
`~/.config/appimage-updater/`	Default configuration directory
`~/.config/appimage-updater/config.json`	Global configuration settings
`~/.config/appimage-updater/apps/`	Directory-based app configurations
`~/.local/share/appimage-updater/appimage-updater.log`	Application logs

Troubleshooting¶

Common Issues¶

Application not found during check:

# Check if application exists and is enabled
appimage-updater list
appimage-updater show MyApp

# Enable if disabled
appimage-updater edit MyApp --enable

No updates found:

# Check with debug logging
appimage-updater --debug check MyApp --dry-run

# Verify repository URL and pattern
appimage-updater show MyApp

Permission errors:

# Check directory permissions
ls -la ~/Applications/MyApp/

# Create directory if missing
mkdir -p ~/Applications/MyApp
chmod 755 ~/Applications/MyApp

Symlink issues:

# Check symlink status
ls -la ~/bin/myapp.AppImage

# Recreate symlink
appimage-updater edit MyApp --symlink ~/bin/myapp.AppImage

# Ensure symlink directory exists
mkdir -p ~/bin

Download failures:

# Check network connectivity
curl -I https://github.com/user/repo/releases

# Adjust global timeout setting
appimage-updater config set timeout-seconds 120

# Try checking again with debug mode
appimage-updater --debug check MyApp

Pattern matching issues:

# Test pattern with debug output
appimage-updater --debug check MyApp --dry-run

# Update pattern for specific files
appimage-updater edit MyApp --pattern "MyApp.*Linux.*\\.AppImage(\\\\..*)?$"

Debug Information¶

# Enable debug logging for detailed output
appimage-updater --debug check --dry-run

# Check application configuration
appimage-updater show MyApp

# View recent log entries
tail -f ~/.local/share/appimage-updater/appimage-updater.log

# Check for specific errors
grep ERROR ~/.local/share/appimage-updater/appimage-updater.log

Getting Help¶

Use --help with any command for detailed options
Check the Usage Guide for complete command documentation
Review Examples for common use cases
See Configuration for advanced settings

Configuration Files¶

Directory-Based Configuration¶

AppImage Updater uses a directory-based configuration structure with separate files for each application:

~/.config/appimage-updater/
├── config.json              # Global configuration and defaults
└── apps/                    # Application configurations
    ├── freecad.json         # FreeCAD configuration
    ├── orcaslicer.json      # OrcaSlicer configuration
    ├── bambustudio.json     # BambuStudio configuration
    └── ...                  # Other application configs

Each application file contains:

{
  "applications": [
    {
      "name": "FreeCAD",
      "source_type": "github",
      "url": "https://github.com/FreeCAD/FreeCAD",
      "download_dir": "/home/user/Applications/FreeCAD",
      "pattern": "(?i)FreeCAD.*\\.(zip|AppImage)(\\.(|current|old))?$",
      "enabled": true,
      "prerelease": false,
      "checksum": {
        "enabled": true,
        "pattern": "{filename}-SHA256.txt",
        "algorithm": "sha256",
        "required": false
      },
      "rotation_enabled": false,
      "retain_count": 3,
      "symlink_path": null
    }
  ]
}

Note: The old single-file format with all applications in config.json is no longer supported.

Example Workflows¶

Daily Automation¶

Set up a cron job to check for updates daily:

# Add to crontab (crontab -e)
0 9 * * * appimage-updater check

Weekly Updates with Notifications¶

# Create a script that runs weekly
#!/bin/bash
appimage-updater check > /tmp/appimage-updates.log 2>&1
if [ $? -eq 0 ]; then
    notify-send "AppImage Updates" "Check completed successfully"
else
    notify-send "AppImage Updates" "Updates failed - check logs"
fi

Next Steps¶

Learn about Configuration options in detail
Explore all Commands and their options
See more Examples for common use cases
Check the Architecture Guide for development