Introduction

What is Soar?

Soar is a fast, modern, bloat-free distro-independent package manager that just works. Supports static binaries, AppImages, and other portable formats.

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
By following freedesktop.org specifications, Soar ensures consistent behavior across different Linux desktop environments and distributions.

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

  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
  1. Move the binary to your desired location, for example /usr/local/bin:
sudo mv soar /usr/local/bin/soar
  1. 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/pkgforge/soar.git
  1. Navigate to the Soar directory:
cd soar
  1. Build and install the project:
cargo install --path .
  1. 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.toml. If this file doesn't exist, Soar will use the defaults.

Configuration Options

Default Configuration

# Directory where Soar stores it's core database 
db_path = "~/.local/share/soar/db"
# Directory where Soar stores binary symlinks
bin_path = "~/.local/share/soar/bin"
# Directory where Soar stores repository metadata databases
repositories_path = "~/.local/share/soar/repos"
# Enable/disable parallel downloads
parallel = true
# Maximum number of concurrent downloads
parallel_limit = 4
# Maximum number of concurrent downloads for GHCR package
ghcr_concurrency = 8
# Maximum number of results to show in search
search_limit = 20
# Default profile to use for operations
# Do not change this after first setup, unless you want to do some manual work moving directories
# (we'll introduce a way to change it in future)
default_profile = "default"
# Currently unused, this will be used to identify whether to enable cross-repo updates
cross_repo_updates = false

[[repositories]]
name = "bincache"
url = "https://meta.pkgforge.dev/bincache/x86_64-Linux.json"

[[repositories]]
name = "pkgcache"
url = "https://meta.pkgforge.dev/pkgcache/x86_64-Linux.json"

# Profile with name `default`
[profile.default]
# Root path for the profile
root_path = "~/.local/share/soar"
# Packages path for the profile. Can be derived from `root_path` if not provided.
packages_path = "~/.local/share/soar/packages"
The `db_path`, `bin_path` and `repositories_path` is derived from the root path of `default_profile` if not provided explicitly.

Troubleshooting

Common Configuration Issues

  1. Invalid TOML Syntax

    • 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 all the paths
    • Check file permissions for the config file

  4. Duplicate Repository/Profile Names

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

Profiles

Soar supports multiple installation profiles, allowing you to install and manage packages in different locations. This is particularly useful when you want to maintain separate package sets for different purposes or environments.

Profile Configuration

Each profile is defined in the configuration file under the [profile.] section. The minimal profile configuration requires:

[profile.<name>]
root_path = "/path/to/profile/root"

This will create packages directory inside the root_path where the packages will be installed. Soar will also create cache directory inside the root_path if you use command that rely on cache. It is not allowed to set cache path explicitly.

Using Profile

You can specify which profile to use for any Soar command using the --profile flag:

soar --profile dev add curl
soar --profile testing add bat

If no profile is specified, Soar uses the default_profile defined in the configuration.

Example Profile Configuration

Here's an example configuration with multiple profiles:

# Default profile for general use
[profile.default]
root_path = "~/.local/share/soar"

# Development profile for development tools
[profile.dev]
root_path = "~/dev/tools"
packages_path = "~/dev/tools/packages"

# Testing profile for experimental packages
[profile.testing]
root_path = "~/testing/soar"
The same installation and metadata database files are shared among all profiles. Do not to change existing profile names as it might break things, unless you haven't installed anything yet. But, you can add however many new profiles you would like to. You will be able to change profile names using soar CLI once profile naming feature is introduced which will move the packages and database accordingly as you update profile names.

Maintenance

This section covers essential features that are fundamental to Soar's operation and maintenance.

Self Management

Soar provides commands to manage the package manager itself, including updating to newer versions and complete uninstallation.

Update Soar

soar self update

Updates Soar to the latest version by downloading pre-compiled binaries from GitHub releases.

You can control which release channel to use through environment variables:

  • SOAR_NIGHTLY=1 Switches to the nightly (development) channel
  • SOAR_RELEASE=1 Switches to the stable release channel

These environment variables take precedence over the currently installed channel. For example:

# Update within current channel
soar self update

# Switch to and update from nightly channel
SOAR_NIGHTLY=1 soar self update

# Switch to and update from stable channel
SOAR_RELEASE=1 soar self update

Uninstall Soar

soar self uninstall

Completely removes Soar from your system

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>
  • pkg_id specific: soar install <package>#<pkg_id>
  • Multiple packages: soar install package1 package2
  • Portable installation (for AppImages): 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 installed packages: soar info

Advanced Operations

Using Package Variants

Switch between different variant of installed packages:

  • Switch family: soar use <package>

Running Packages

Execute packages without installation:

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

Viewing Package Logs

View detailed package information:

  • View build logs: soar log <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 add soar

Installing from Specific pkg_id

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

soar add <package>#<pkg_id>

Example: Install the cat package from the git.busybox.net.busybox.standalone.glibc pkg_id. Yep, a really long pkg_id.

soar add cat#git.busybox.net.busybox.standalone.glibc

Installing from Specific Repository

To install a package from a specific repository:

soar add <package>:<repository_name>

Example: Install the 7z package from the bincache repository

soar add 7z:bincache

Installing Multiple Packages

To install multiple packages, list them after the command:

soar add <package1> <package2> <package3>

Example: Install the bat and 7z packages

soar add bat 7z

Pin package to specific version

To pin package at specific version:

soar add <package>@<version>

Example: Install the soar package and pin at version 0.5.2.

soar add [email protected]
Currently there is no way to unpin the package. This will be introduced gradually.

Installing All Packages provided by a pkg_id

To install all the packages provided by a pkg_id git.busybox.net.busybox.standalone.glibc:

soar add '#git.busybox.net.busybox.standalone.glibc'

OR, if you don't know full pkg_id but know cat is in it. This will search for all pkg_ids cat is in and prompt you to choose one:

soar add 'cat#all'

Force Installation

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

soar add <package> --force

Example: Install the bat package even if it already exists

soar add bat --force

Non-Interactive Installation

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

soar add <package> --yes

Example: Install the cat package without confirmation

soar add cat --yes
Note: The `--yes` flag is useful for non-interactive installations, but it's generally recommended to use it with caution. It will install the first package if multiple packages are found.

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
If you just provide the package name without pkg_id, it'll remove all installed packages with that name.

Removing Package From Specific pkg_id

soar remove <package>#<pkg_id>

Example: Remove cat from git.busybox.net.busybox.standalone.glibc pkg_id.

# Remove from specific pkg_id
soar remove cat#git.busybox.net.busybox.standalone.glibc

Removing all package installed at once using pkg_id

Example: Remove all packages from git.busybox.net.busybox.standalone.glibc pkg_id.

soar remove '#<pkg_id>'

OR, if you don't know full pkg_id but know cat is in it. This will search for all pkg_ids cat is in and prompt you to choose one:

soar remove 'cat#all'
It will ignore the packages that are installed explicitly.

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
The update process ignores the updates from another repository than the one the package is installed from. The profile flag has no effect on package installation path; it'll use the profile used at the time of installation.

Search Packages

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

To search for packages, use the soar search command:

soar search <query>

Search Options

The search checks for the partial match in pkg_id, pkg_name, pkg and target from provides.

For exact case matching:

soar search <query> --exact

Query Command

The query command provides detailed package information:

soar query bat

Search Patterns

Partial Matching

# Matches any package containing "fire"
soar search fire

# Matches any package containing "code"
soar search code

List Packages

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

List Avaialable Packages

To list all available packages:

soar list

List Installed Packages

To list all installed packages:

soar info

It will list all the installed packages alongside the total size used by each package. This will also report partially installed packages as broken.

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 list out installed cat packages and switch:

soar use cat

It'll list out all the cat packages installed from different pkg_id, version or repositories and let you choose one to use. The one you choose will be linked to bin path alongside its provides.

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
Unlike temporary execution, running a package does store the files on disk. This approach provides faster subsequent runs while maintaining system organization.

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
This approach ensures that large packages don't fill up memory-based temporary storage while still maintaining separation from system-installed packages.

Miscellaneous

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

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/pkgforge/soar/releases/download/nightly/soar-nightly-x86_64-linux

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

soar download https://github.com/pkgforge/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/pkgforge/soar/releases/download/nightly/soar-nightly-x86_64-linux https://github.com/pkgforge/soar/releases/download/nightly/soar-nightly-aarch64-linux -o downloads/
It currently doesn't support multiple custom output filenames. So if you specify an output filename, it will be used for all downloads, meaning only the last download will be saved if you specify multiple URLs.