Installing Packages

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

Installation Flow

graph TD
    A["soar install <input>"] --> B{"Input type?"}
    B -->|"package name"| C["Search repositories"]
    B -->|"name#pkg_id"| D["Search specific family"]
    B -->|"name:repo"| E["Search specific repo"]
    B -->|"URL"| F["Download from URL"]

    C --> G{"Multiple matches?"}
    D --> G
    E --> H["Download & Install"]
    F --> H

    G -->|"Yes"| I{"--yes flag?"}
    G -->|"No"| H
    I -->|"Yes"| J["Select first match"]
    I -->|"No"| K["Prompt user to select"]
    J --> H
    K --> H

    style A fill:#161b22,stroke:#58a6ff,color:#e6edf3
    style H fill:#1c2128,stroke:#3fb9a2,color:#e6edf3

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 from URL

You can install packages directly from a URL:

soar add <url>

Example: Install an AppImage from a URL

soar add https://example.com/releases/myapp-1.0.0.appimage

Overriding Package Metadata

When installing from a URL, Soar attempts to automatically detect package metadata. You can override this behavior using the following flags:

Basic Example:

soar add https://example.com/app.appimage --name myapp --version 2.0.0

Portable Installation:

soar add https://example.com/app.AppImage \
  --name myapp \
  --portable-home ~/myapp

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 soar@0.5.2

Warning: 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'

Portable Installation

Portable mode creates symlinks for application data directories (home, config, share, cache) to custom locations. This keeps application data self-contained or allows running from removable media.

Warning: Portable mode only works for AppImage, FlatImage, RunImage, and Wrappe packages. Static binaries and archive packages do not support portable mode.

To install a package in portable mode:

soar add <package> --portable

You can specify custom directories for different data types:

Example: Install with a custom home directory

soar add obsidian.AppImage --portable-home ~/.obsidian-data

Example: Install with multiple custom directories

soar add myapp.AppImage --portable-home ~/myapp --portable-config ~/myapp/config --portable-share ~/myapp/share --portable-cache ~/myapp/cache

Note: Portable options create symlinks from the package’s expected directories to your custom locations. These settings are stored in the database and reused on reinstallation.

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

Binary-Only Installation

By default, Soar extracts all files from a package. The --binary-only flag skips extracting non-essential files to save disk space:

soar add <package> --binary-only

This flag excludes:

• *.png and *.svg (icon files)
• *.desktop (desktop entry files)
• LICENSE (license files)
• CHECKSUM (checksum files)

Example: Install ripgrep without icons, desktop files, and license

soar add ripgrep --binary-only

Note: This option is useful for minimal installations. However, excluding desktop files (*.desktop) means the package won’t appear in your system’s application menu.

Suppress Package Notes

Some packages display important information after installation. To suppress these notes, use the --no-notes flag:

soar add <package> --no-notes

Example: Install neovim without displaying post-installation notes

soar add neovim --no-notes

Note: Package notes often contain critical setup instructions or configuration tips. Use this flag with caution.

Interactive Installation

By default, Soar automatically installs packages. To explicitly enable interactive prompts (for example, to choose between multiple versions or variants), use the --ask flag:

soar add <package> --ask

This is the opposite of --yes and ensures Soar will always prompt for confirmation before proceeding with installation.

Skip Signature Verification

By default, Soar verifies package signatures for security. To skip signature verification (not recommended unless you trust the source), use the --no-verify flag:

soar add <package> --no-verify

Security Warning: Skipping signature verification exposes you to potentially compromised packages. Only use --no-verify with packages from trusted sources or during testing/development.

Example: Install a package from a trusted development build

soar add https://internal.example.com/builds/myapp.appimage --no-verify

Package ID Override

To explicitly specify the package ID (useful when multiple packages share the same name), use the --pkg-id flag:

soar add <package> --pkg-id <package_id>

Example: Install cat from a specific package ID

soar add cat --pkg-id git.busybox.net.busybox.standalone.glibc

This is equivalent to using the cat#git.busybox.net.busybox.standalone.glibc syntax but can be more readable in scripts.

Show Package Information

To interactively browse and select package variants before installing, use the --show flag:

soar add <package> --show

This opens an interactive picker that displays:

• All available versions and variants of the package
• [installed] marker next to already-installed versions
• Package details (name, version, repository, pkg_id)

Example: Browse all bat variants interactively

soar add bat --show

Note: Unlike a non-interactive display, --show always presents an interactive selection menu. You can choose which variant to install or cancel without installing anything.

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.

Advanced Scenarios

Batch Installation

You can combine multiple installation options for complex scenarios:

soar add bat --yes --no-notes
soar add ripgrep --yes --binary-only

Portable Application Setup

For AppImage/FlatImage/RunImage/Wrapper applications that need to be completely self-contained (e.g., on a USB drive):

soar add obsidian.AppImage \
  --portable-home /media/usb/obsidian/home \
  --portable-config /media/usb/obsidian/config

Installing All Packages from a pkg_id

To install all packages provided by a specific package ID family:

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

Or if you know one package name but want to see all pkg_ids it belongs to:

soar add 'cat#all'

Troubleshooting

Package Not Found

Check package name spelling, sync repositories, or try installing from URL directly:

soar search <name>
soar sync

Multiple Packages Found

Use --ask to choose interactively, specify repository with <package>:<repo>, or use --yes for first match.

Permission Denied

Verify profile permissions or use sudo with --system mode.

Portable Mode Not Working

Portable mode only works for AppImage, FlatImage, RunImage, and Wrappe packages. Static binaries and archives are not supported.

For more troubleshooting, see Health Check

Related Topics

• Removing Packages
• Updating Packages
• Searching Packages