Download Files

This section covers Soar’s powerful download capabilities.

Soar provides powerful download capabilities with support for direct URLs, GitHub releases, GitLab releases, and GitHub Container Registry (GHCR). The download command includes advanced filtering to narrow down options, interactive asset selection when multiple matches remain, and automatic archive extraction.

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 or directory, use the --output or -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/

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

Package Downloads

Download packages directly from configured Soar repositories:

# Download by package name
soar download neovim

# Download specific version
soar download neovim@0.9.5

# Download from specific repo
soar download repo/neovim

Download Command Options

Confirmation Options

Option	Short	Description
`--yes`	`-y`	Skip confirmation prompts (useful for scripts)

Output Options

Option	Short	Description
`--output`	`-o`	Set output filename or directory

Filtering and Selection Options

Option	Short	Description
`--regex`	`-r`	Filter assets using regular expression pattern (works with all sources)
`--glob`	`-g`	Filter assets using glob pattern (works with all sources)
`--match`	-	Filter assets by keyword substring matching (works with all sources)
`--exclude`	-	Exclude assets matching this pattern (works with all sources)
`--exact-case`	-	Enable case-sensitive matching (default is case-insensitive)

Filter Behavior: Filters narrow down the available assets. If multiple assets remain after filtering, Soar shows an interactive selection prompt for you to choose manually. Use --yes to skip the prompt and automatically download the first matching asset.

Source Options

Option	Description
`--github`	Download from GitHub releases using format `owner/repo[@tag]`
`--gitlab`	Download from GitLab releases using format `owner/project[@tag]`
`--ghcr`	Download from GitHub Container Registry using format `owner/image[:tag]`

Extraction Options

Option	Description
`--extract`	Automatically extract downloaded archives (supports .tar, .tar.gz, .tar.xz, .tar.zst, .zip)
`--extract-dir`	Custom extraction directory (default: current directory or output path)

File Handling Options

Option	Description
`--skip-existing`	Skip download if file already exists
`--force-overwrite`	Overwrite existing files without prompting

Download Sources

Direct URLs

Download any file from the internet using direct URLs:

# Single file
soar download https://example.com/file.tar.gz

# Save to specific location
soar download https://example.com/file.tar.gz -o /path/to/download/

# With automatic extraction
soar download https://example.com/file.tar.gz --extract

URL Auto-Detection: Soar automatically detects GitHub/GitLab/GHCR URLs. You don’t need --github/--gitlab/--ghcr flags when using full URLs.

GitHub Releases

Download assets from GitHub releases using the --github flag:

# Basic format: owner/repo
soar download --github pkgforge/soar

# Specific tag/release
soar download --github pkgforge/soar@v1.0.0

# Filter by architecture using regex
# Shows interactive selection if multiple assets match 'x86_64-linux'
soar download --github pkgforge/soar --regex 'x86_64-linux'

# Filter by multiple patterns
# Shows interactive selection if both x86_64 and aarch64 matches exist
soar download --github pkgforge/soar --regex 'x86_64-linux|aarch64-linux'

# Use --yes to skip interactive selection and download first match
soar download --github pkgforge/soar --regex 'x86_64-linux' --yes

# Download and extract automatically
soar download --github pkgforge/soar@nightly --regex 'x86_64-linux' --extract

# Exclude certain assets
soar download --github pkgforge/soar --exclude 'musl' --exclude 'debug'

Latest Release Behavior: Without a tag or with @latest, Soar downloads the latest stable release (skips prereleases). Use @tag-name for specific versions including prereleases.

GitHub Asset Selection Examples

# Download only musl builds
# Interactive: shows all musl builds if multiple match
soar download --github cli/cli --glob '*-musl*'

# Download only .tar.gz files
# Interactive: shows all .tar.gz files if multiple match
soar download --github pkgforge/soar --glob '*.tar.gz'

# Match specific keywords
# Interactive: shows all assets containing 'appimage' if multiple match
soar download --github neovim/neovim --match 'appimage'

# Auto-download first match (skip interactive selection)
soar download --github cli/cli --glob '*-musl*' --yes

# Case-sensitive matching
soar download --github pkgforge/soar --exact-case --regex 'Linux'

GitLab Releases

Download assets from GitLab releases using the --gitlab flag:

# Basic format: owner/project
soar download --gitlab gitlab-org/gitlab

# Specific tag/release
soar download --gitlab gitlab-org/gitlab@v16.0.0

# Filter by platform
soar download --gitlab gitlab-org/gitlab --regex 'linux-amd64'

# Download and extract
soar download --gitlab gitlab-org/gitlab@v16.0.0 --regex 'linux-amd64' --extract

Latest Release Behavior: Without a tag or with @latest, Soar downloads the latest stable release (skips prereleases). Use @tag-name for specific versions including prereleases.

GitLab Asset Selection Examples

# Download only ARM64 builds
# Interactive: shows all ARM64 builds if multiple match
soar download --gitlab gitlab-org/gitlab --glob '*-arm64*'

# Download specific file types
# Interactive: shows all .tar.xz files if multiple match
soar download --gitlab gitlab-org/gitlab --glob '*.tar.xz'

# Auto-download first match (skip interactive selection)
soar download --gitlab gitlab-org/gitlab --glob '*-arm64*' --yes

# Exclude debug builds
soar download --gitlab gitlab-org/gitlab --exclude 'debug'

GitHub Container Registry (GHCR)

Download container images from GitHub Container Registry:

# Basic format: owner/image
soar download --ghcr pkgforge/soar

# Specific tag
soar download --ghcr pkgforge/soar:latest

# Specific version
soar download --ghcr pkgforge/soar:v1.0.0

# Multiple tags
soar download --ghcr pkgforge/soar:alpine --ghcr pkgforge/soar:slim

Automatic Retry: GHCR downloads automatically retry on rate limits (HTTP 429) or network errors (up to 5 attempts with 5-second delays).

Asset Selection Patterns

How Asset Selection Works

Soar’s filtering works in two stages:

Filtering Stage: Filters (--regex, --glob, --match, --exclude) narrow down the list of available assets
Selection Stage:
- If exactly one asset matches → automatically downloaded
- If multiple assets match and --yes is NOT set → interactive selection prompt appears
- If multiple assets match and --yes IS set → first matching asset is automatically downloaded

Key Point: Filters reduce the options but don’t automatically select which file to download when multiple matches remain. The user must choose interactively unless --yes is specified.

Pattern Matching Options

Soar provides three ways to filter assets:

Regex (--regex / -r): Full regular expression support
Glob (--glob / -g): Shell-style glob patterns
Match (--match): Simple substring matching

Regex Examples

# Match specific architecture
# Auto-downloads if exactly one match, otherwise shows selection
soar download --github pkgforge/soar --regex 'x86_64-unknown-linux-gnu'

# Match multiple architectures
# Interactive: shows both x86_64 and aarch64 if both exist
soar download --github pkgforge/soar --regex '(x86_64|aarch64)-linux'

# Match version patterns
soar download --github pkgforge/soar --regex 'v[0-9]+\.[0-9]+\.[0-9]+'

# Match file extensions
# Interactive: shows all .tar.gz and .zip files if multiple match
soar download --github pkgforge/soar --regex '\.(tar\.gz|zip)$'

Glob Examples

# Match all Linux builds
# Interactive: shows all Linux builds if multiple match
soar download --github pkgforge/soar --glob '*linux*'

# Match specific file type
soar download --github pkgforge/soar --glob '*.tar.gz'

# Match architecture pattern
soar download --github pkgforge/soar --glob '*-x86_64-*'

# Match AppImages
# Auto-downloads if only one AppImage exists
soar download --github neovim/neovim --glob '*.AppImage'

Keyword Match Examples

# Find assets containing "linux"
# Interactive: shows all assets with "linux" if multiple match
soar download --github pkgforge/soar --match linux

# Find assets containing "musl"
soar download --github pkgforge/soar --match musl

# Multiple keywords (AND logic - all must match)
# Narrows down to assets containing both "linux" AND "x86_64"
soar download --github pkgforge/soar --match linux --match x86_64

Exclusion Patterns

Use --exclude to filter out unwanted assets. Combined with other filters, this narrows down the selection pool. If multiple assets remain after exclusions, interactive selection is shown:

# Exclude musl builds
# Shows selection of non-musl builds if multiple remain
soar download --github pkgforge/soar --exclude 'musl'

# Exclude debug builds
soar download --github pkgforge/soar --exclude 'debug'

# Multiple exclusions
soar download --github pkgforge/soar --exclude 'musl' --exclude 'debug' --exclude 'test'

# Combine with inclusion patterns
# Shows Linux builds excluding musl (interactive if multiple match)
soar download --github pkgforge/soar --regex 'linux' --exclude 'musl'

Case Sensitivity

By default, pattern matching is case-insensitive. Use --exact-case for case-sensitive matching:

# Case-insensitive (default) - matches Linux, LINUX, linux
soar download --github pkgforge/soar --match linux

# Case-sensitive - only matches lowercase "linux"
soar download --github pkgforge/soar --match linux --exact-case

# Case-sensitive regex
soar download --github pkgforge/soar --regex '[A-Z]{2}' --exact-case

Archive Extraction

Soar can automatically extract downloaded archives:

Supported Formats

.tar
.tar.gz / .tgz
.tar.xz / .txz
.tar.zst / .tzst
.zip

Extraction Examples

# Extract to current directory
soar download https://example.com/file.tar.gz --extract

# Extract to specific directory
soar download https://example.com/file.tar.gz --extract --extract-dir /opt/app

# Download GitHub release and extract
soar download --github pkgforge/soar@v1.0.0 --regex 'x86_64-linux' --extract

# Extract with custom output
soar download https://example.com/file.tar.gz -o myfile.tar.gz --extract --extract-dir ./mydir

File Handling

Skip Existing Files

Avoid re-downloading files that already exist:

# Skip if file exists (default behavior)
soar download https://example.com/file.tar.gz --skip-existing

# Useful for batch downloads
soar download --github pkgforge/soar --regex 'linux' --skip-existing

Force Overwrite

Overwrite existing files without prompting:

# Force overwrite
soar download https://example.com/file.tar.gz --force-overwrite

# Combine with extraction
soar download https://example.com/file.tar.gz --extract --force-overwrite

Non-Interactive Mode

Skip all confirmation prompts with --yes. When multiple assets match your filters, --yes automatically downloads the first matching asset instead of showing an interactive selection:

# Download without confirmation
soar download https://example.com/file.tar.gz --yes

# Batch download with all options
# Skips interactive selection and downloads first match
soar download --github pkgforge/soar --regex 'linux' --extract --yes --skip-existing

# When multiple assets match, --yes picks the first one automatically
soar download --github cli/cli --regex 'linux' --yes

Interactive Selection

When multiple assets match your filters and --yes is not set, Soar displays an interactive selection prompt:

soar download --github cli/cli --regex 'linux'
# > Select an asset (1-4):
#   1. cli-linux-amd64.rpm (95.2 MB)
#   2. cli-linux-arm64.deb (89.1 MB)
#   3. cli-linux-386.tar.gz (91.5 MB)
#   4. cli-linux-amd64.tar.gz (95.2 MB)

The selection works as follows:

Exactly 1 match: Automatically downloads without prompting
Multiple matches + no --yes: Shows interactive prompt (as shown above)
Multiple matches + --yes: Automatically downloads the first matching asset

Automatic vs Interactive: Use filters to narrow down options. If only one asset remains after filtering, it downloads automatically. If multiple remain, you’ll be prompted to choose unless you use --yes to accept the first match.

Advanced Examples

Multi-Architecture Download

# Download multiple architectures
# Shows interactive selection if both x86_64 and aarch64 builds exist
soar download --github pkgforge/soar --regex '(x86_64|aarch64)-linux' -o ./binaries/

# Auto-download first architecture match
soar download --github pkgforge/soar --regex '(x86_64|aarch64)-linux' -o ./binaries/ --yes

Latest Release from Multiple Sources

# Download from GitHub
soar download --github pkgforge/soar@latest --regex 'linux' --extract

# Download from GitLab
soar download --gitlab gitlab-org/gitlab@latest --regex 'amd64' --extract

Filter and Extract Workflow

# Download, filter, and extract in one command
soar download --github neovim/neovim \
  --glob 'nvim-linux64.tar.gz' \
  --extract \
  --extract-dir ./nvim \
  --output nvim.tar.gz

Batch Downloads with Exclusions

# Download all Linux builds except musl
# Shows interactive selection if multiple non-musl Linux builds remain
soar download --github pkgforge/soar \
  --regex 'linux' \
  --exclude 'musl' \
  --exclude 'debug' \
  -o ./builds/

# Auto-download first match
soar download --github pkgforge/soar \
  --regex 'linux' \
  --exclude 'musl' \
  --exclude 'debug' \
  -o ./builds/ \
  --yes

Container Image Management

# Pull multiple image variants
soar download --ghcr pkgforge/soar:alpine
soar download --ghcr pkgforge/soar:slim
soar download --ghcr pkgforge/soar:latest

Tips and Best Practices

Use --glob for simple patterns: Easier to read than regex for common cases
Combine filters: Use both inclusion (--regex/--glob) and exclusion (--exclude) for precise control
Understand selection behavior: Filters narrow down options, but if multiple assets remain, you’ll be prompted to choose (or use --yes for automatic first-match download)
Test patterns first: Use --yes only after verifying your filters work correctly
Extraction paths: Use --extract-dir to keep downloads organized
Batch operations: --skip-existing is essential for re-running download scripts
Case sensitivity: Most patterns are case-insensitive by default; use --exact-case when needed
Asset names: GitHub/GitLab asset names typically include architecture, OS, and file type
Latest releases: Use @latest or omit the tag to get the newest stable release (prereleases are skipped)
Filter universality: --regex, --glob, --match, and --exclude work with all sources (GitHub, GitLab, GHCR)
URL auto-detection: Full URLs are automatically detected; no need for --github/--gitlab/--ghcr flags
Package downloads: Can download packages directly by name from configured repositories

Keyboard shortcuts

soar documentation