Introduction

What is Soar?

Soar is a fast Linux package manager that doesn't suck. Works with static binaries, AppImages, and other portable stuff.

Key Features

Universal Package Support

• Binary Packages: Direct installation of pre-compiled binaries - no system compilation needed, only bandwidth and storage
• AppImage Integration: Smart desktop integration with automatic icon scaling, menu entries, and runtime fixes
• FlatImage Support: Seamless handling of Flatpak-style packages
• Multiple Format Handling: Extensible architecture supporting various package formats

Desktop Integration

Soar strictly follows the freedesktop.org specifications for seamless Linux desktop integration.

• Automatic Desktop Entries: Seamless integration with desktop menus through properly configured desktop files and icons
• Icon Management: Automatic scaling and integration of application icons across all system themes and resolutions
• Smart Symlink Handling: Intelligent binary path management
• Portable Configurations: Take your entire setup anywhere - relocate all apps and their configurations to any device

Why Choose Soar?

Soar stands out from traditional package managers by offering:

1. Speed and Efficiency

   • Uses pre-built binary cache - no unsafe local compilation or shell scripts running on your machine
   • Built with Rust for reliable, fast performance instead of shell script patchworks
   • Parallel downloads and installations

2. User Experience

   • Intuitive commands that make sense without memorizing manpages
   • Clear, human-friendly error messages instead of cryptic codes
   • Real-time progress feedback during operations

3. Flexibility

   • Support for multiple formats: static binaries, AppImages, FlatImages, AppBundles, and more
   • Fully portable configurations - take your entire setup anywhere

4. Integration

   • Comprehensive desktop environment integration across all package formats
   • Smart handling of icons, menus, and file associations
   • Intelligent runtime fixes and compatibility layers

5. Security

   • All packages built on secure remote CI servers with transparent build logs
   • Build logs available for auditing via soar log <package>
   • Cryptographic verification using BLAKE3 checksums for all downloads
   • No arbitrary script execution on your machine

Installation

There are several ways to install Soar on your Linux system. Choose the method that best suits your needs.

Quick Installation

Install Script

The fastest way to install Soar is using our installation script:

curl -fsSL https://soar.qaidvoid.dev/install.sh | sh

Or if you prefer using wget:

wget -qO- https://soar.qaidvoid.dev/install.sh | sh

The install script supports several environment variables to customize the installation:

• SOAR_VERSION: Specify the version to install

# Install specific version
curl -qfsSL "https://soar.qaidvoid.dev/install.sh" | SOAR_VERSION=0.4.0 sh

# Install latest release
curl -qfsSL "https://soar.qaidvoid.dev/install.sh" | SOAR_VERSION=latest sh

# Install nightly build
curl -qfsSL "https://soar.qaidvoid.dev/install.sh" | SOAR_VERSION=nightly sh

• SOAR_INSTALL_DIR: Specify custom installation directory

curl -qfsSL "https://soar.qaidvoid.dev/install.sh" | SOAR_INSTALL_DIR=~/.bin sh

Cargo (crates.io)

cargo install soar-cli

Manual Installation

From Binary Releases

1. Visit the releases page

2. Download the appropriate binary for your architecture:

   • soar-x86_64-linux for 64-bit Intel/AMD systems
   • soar-aarch64-linux for 64-bit ARM systems

3. Make the binary executable:

chmod +x soar

4. Move the binary to your desired location, for example /usr/local/bin:

sudo mv soar /usr/local/bin/soar

5. Verify the installation by running soar --version:

soar --version

This should output the version number of the installed Soar binary.

From Source

To install Soar from source, you need to have Rust and Cargo installed. Follow these steps:

1. Clone the Soar repository:

git clone https://github.com/QaidVoid/soar.git

2. Navigate to the Soar directory:

cd soar

3. Build and install the project:

cargo install --path .

4. Verify the installation by running soar --version:

soar --version

This should output the version number of the installed Soar binary.

Next Steps

After installing Soar, you might want to:

1. Configure Soar for your specific needs
2. Learn about package management
3. Try installing your first package

Configuration

Soar offers flexible configuration options to customize its behavior according to your needs. This section explains how to configure Soar and details all available configuration options.

Configuration File

Soar uses a configuration file located at ~/.config/soar/config.json. If this file doesn't exist, Soar will create one with default settings on first run.

Configuration Options

Global Settings

Repository Configuration

Each repository in the repositories array can be configured with the following options:

Example Configurations

Default Configuration

{
    "soar_path": "$HOME/.soar",
    "parallel": true,
    "parallel_limit": 2,
    "repositories": [
        {
            "name": "ajam",
            "url": "https://bin.ajam.dev/x86_64",
            "metadata": "METADATA.AIO.json",
            "sources": {
                "bin": "https://bin.ajam.dev/x86_64",
                "pkg": "https://pkg.ajam.dev/x86_64",
                "base": "https://bin.ajam.dev/x86_64/Baseutils"
            }
        }
    ]
}

Validation

Soar automatically validates your configuration file when loading it. If there are any issues, it will display helpful error messages indicating what needs to be corrected.

Common validation checks include:

• Valid URLs for repositories
• Unique repository names
• Valid parallel_limit values (must be positive)
• Accessible soar_path directory

Troubleshooting

Common Configuration Issues

1. Invalid JSON Syntax

   • Missing or extra commas
   • Unclosed brackets or braces
   • Missing quotation marks around strings

2. Invalid Repository URL

   • Ensure URLs are properly formatted and accessible
   • Check for trailing slashes in URLs

3. Permission Issues

   • Verify write permissions for soar_path
   • Check file permissions for the config file

4. Duplicate Repository Names

   • Ensure each repository has a unique name
   • Check for case-sensitive duplicates

Package Management

Soar provides a comprehensive set of commands for managing packages on your system. This section covers all package management operations available in Soar.

Core Operations

Installing Packages

Install packages using various methods:

• Basic installation: soar install <package>
• Family-specific: soar install <family>/<package>
• Collection-specific: soar install <package>#<collection>
• Multiple packages: soar install package1 package2
• Portable installation: soar install <package> --portable

Removing Packages

Remove installed packages:

• Basic removal: soar remove <package>
• Multiple packages: soar remove package1 package2

Updating Packages

Keep your packages up to date:

• Update all packages: soar update
• Update specific packages: soar update package1 package2

Package Discovery

Searching Packages

Find packages in repositories:

• Basic search: soar search <query>
• Case-sensitive search: soar search <query> --case-sensitive
• Detailed package info: soar query <package>

Listing Packages

View available and installed packages:

• List all packages: soar list
• List from collection: soar list <collection>
• List installed packages: soar info

Advanced Operations

Using Package Variants

Switch between different family of installed packages:

• Switch family: soar use <family>/<package>

Running Packages

Execute packages without installation:

• Run package: soar run <package> [args]

Viewing Package Logs

View detailed package information:

• View build logs: soar logs <package>

Installing Packages

Soar provides several flexible ways to install packages. This guide covers all installation methods and options.

Basic Installation

To install a package, use either the install command or its aliases:

# Using install command
soar install <package>

# Using shorter alias
soar i <package>

# Using add alias
soar add <package>

Example: Install the soar package

soar install soar

Installing from Specific Families

Packages can be organized into families (like categories). To install a package from a specific family:

soar install <family>/<package>

Example: Install the cat package from the busybox family

soar install busybox/cat

Installing from Specific Collections

Packages can also be organized into collections. To install a package from a specific collection:

soar install <package>#<collection>

Example: Install the 7z package from the bin collection

soar install 7z#bin

Installing Multiple Packages

To install multiple packages, list them after the command:

soar install <package1> <package2> <package3>

Example: Install the bat and 7z packages

soar install bat 7z

Force Installation

To force installation even if the package already exists, use the --force flag:

soar install <package> --force

Example: Install the bat package even if it already exists

soar install bat --force

Non-Interactive Installation

By default, Soar prompts for confirmation before installing packages if multiple packages are found. To skip this prompt, use the --yes flag:

soar install <package> --yes

Example: Install the cat package without confirmation

soar install cat --yes

Remove Packages

Soar provides straightforward commands for removing installed packages from your system. This guide covers all removal options and scenarios.

Usage

To remove a package, use either the remove command or its aliases:

Removing Single Package

# Using remove command
soar remove <package>

# Using shorter alias
soar r <package>

# Using del alias
soar del <package>

Example: Remove 7z

soar remove 7z

Removing Multiple Packages

Remove multiple packages in a single command:

soar remove <package1> <package2> <package3>

Example: Remove 7z and bat

soar remove 7z bat

Removing Package From Specific Family

soar remove <family>/<package>

Example: Remove cat from coreutils family.

# Remove specific family
soar remove coreutils/cat

Verification

After removal, you can verify that a package was successfully removed:

# Check if package is still installed
soar info | grep <package>

Update Packages

Soar provides efficient commands to keep your packages up to date. This guide covers all update operations and scenarios.

Basic Update

To update all installed packages to their latest versions:

soar update

To update specific packages:

soar update <package1> <package2>

Example: Update Specific Packages

soar update 7z bat

Automated Updates

While Soar doesn't include a built-in update scheduler, you can automate updates using system tools:

Using Cron

# Add to crontab
0 0 * * * soar update

Using Systemd Timer

[Unit]
Description=Daily Soar Update

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Search Packages

Soar provides powerful search capabilities to help you find the packages you need. This guide covers all search operations and features.

Basic Search

To search for packages, use the soar search command:

soar search <query>

Search Options

Case-Sensitive Search

For exact case matching:

soar search <query> --case-sensitive

Query Command

The query command provides detailed package information:

$ soar query firefox.AppImage

Search Patterns

Partial Matching

# Matches any package containing "fire"
soar search fire

# Matches any package containing "code"
soar search code

Family-Specific Search

# List all coreutils packages
soar search coreutils/

List Packages

Soar provides commands to list available and installed packages. This guide covers all listing operations and features.

Basic Listing

To list all available packages:

soar list

List Installed Packages

To list all installed packages:

soar info

List Available Packages

To list all available packages:

soar list

List from Collection

To list all available packages from a specific collection:

soar list <collection>

Use Package From Different Family

Soar allows you to switch between different family of installed packages without uninstalling one. This feature is particularly useful when you need to switch between different family providing the same package.

Usage

To switch to a package from different family:

soar use <family>/<package>

Example: Switch to coreutils-glibc

soar use coreutils-glibc/cat

Example: Switch to busybox

soar use busybox/cat

Run Packages

Soar allows you to run packages without installing them permanently on your system. While the package files are still downloaded and stored, they aren't integrated into your system PATH or desktop environment. This feature is perfect for trying out applications or running one-off tasks.

Basic Usage

To run a package:

soar run <package>

Example: Run feroxbuster

soar run feroxbuster

How It Works

When you run a package:

1. Download and Storage

   • Downloads the package to Soar's managed directory
   • Stores in a separate location from installed packages
   • Maintains package files for future runs

2. Execution

   • Executes directly from Soar's managed directory
   • Uses isolated binary path
   • Maintains separation from system-installed versions

3. Management

   • Keeps package files for future use
   • Doesn't add to system PATH
   • No desktop environment integration

Storage Location

Soar stores "run-only" packages in its managed directory structure:

• Not in /tmp (to avoid memory pressure on systems with tmpfs)
• Separate from permanently installed packages
• Managed alongside other Soar data
• Preserved for future runs, but removed after 8 hours

Miscellaneous

This section covers additional features and utilities in Soar that are not directly related to package management.

Features

Download Files

Download arbitrary files from the internet.

Health Check

System health verification to run AppImages, FlatImages, and other bundled executables.

Download Files

Soar provides the ability to download arbitrary files from the internet.

Basic Usage

To download a file, use the download command or the dl: alias:

soar download <url>

Example: Download Soar nightly

soar download https://github.com/QaidVoid/soar/releases/download/nightly/soar-nightly-x86_64-linux

To set the output filename, use the -o flag:

soar download https://github.com/QaidVoid/soar/releases/download/nightly/soar-nightly-x86_64-linux -o soar-nightly

Example: Download multiple files and save them to the downloads directory

soar download https://github.com/QaidVoid/soar/releases/download/nightly/soar-nightly-x86_64-linux https://github.com/QaidVoid/soar/releases/download/nightly/soar-nightly-aarch64-linux -o downloads/

Health Check

Soar provides a health check system to verify the integrity of your package installations and system configuration. This helps identify and resolve potential issues before they become problems. The health checks are performed to ensure that AppImages and other self-contained executables can function properly on the system. These checks are critical for applications that rely on user namespaces and FUSE (Filesystem in Userspace) to operate in a confined environment without requiring root privileges.

Basic Usage

To run a health check:

soar health