gosh

A fast, modern download manager CLI with HTTP/HTTPS multi-connection acceleration and full BitTorrent protocol support. Powered by gosh-dl.

Features

• HTTP/HTTPS Downloads: Multi-connection segmented downloads (up to 16 parallel connections), automatic resume, checksum verification
• BitTorrent: Full protocol support with DHT, PEX, magnet links, encryption, and WebSeeds
• Three Usage Modes: Interactive TUI, direct aria2-style CLI, and scriptable commands
• Cross-Platform: Linux, macOS, and Windows support

Installation

From Source

git clone https://github.com/goshitsarch-eng/gosh-dl-cli
cd gosh-dl-cli
cargo build --release
sudo cp target/release/gosh /usr/local/bin/

From Crates.io

cargo install gosh-dl-cli

Pre-built Binaries

Download from GitHub Releases.

Linux builds: Statically linked with musl for maximum portability across all distributions (including Alpine).

Usage Modes

gosh supports three distinct usage patterns:

1. Interactive TUI Mode

Launch without arguments to enter the full-screen terminal UI:

gosh

TUI Keyboard Shortcuts:

2. Direct Download Mode (aria2-style)

Pass URLs directly to download immediately with progress bars:

# Single download
gosh https://example.com/file.zip

# Multiple parallel downloads
gosh https://example.com/file1.zip https://example.com/file2.zip

# With options
gosh -d /downloads -x 8 --max-speed 5M https://example.com/large-file.iso

# Torrent/Magnet
gosh magnet:?xt=urn:btih:...
gosh /path/to/file.torrent

3. Command Mode

Use subcommands for scriptable operations:

gosh add https://example.com/file.zip
gosh list
gosh status abc123
gosh pause abc123
gosh resume abc123

Direct Download Options

When using direct download mode (gosh URL), the following options are available:

Examples:

# Download with custom headers and user agent
gosh -H "Authorization: Bearer token" --user-agent "MyApp/1.0" https://api.example.com/file

# Download with checksum verification
gosh --checksum sha256:abc123... https://example.com/important-file.iso

# Limit download speed to 5 MB/s with 8 connections
gosh -x 8 --max-speed 5M https://example.com/large-file.zip

# Download specific files from a torrent
gosh --select-files 0,2,5 /path/to/multi-file.torrent

# Sequential download for streaming
gosh --sequential magnet:?xt=urn:btih:...

Commands Reference

gosh add

Add a new download to the queue.

gosh add [OPTIONS] <URL>...

Options:
  -d, --dir <PATH>            Output directory
  -o, --out <NAME>            Output filename (single download only)
  -p, --priority <PRIORITY>   Priority [low, normal, high, critical]
  -w, --wait                  Wait for download to complete (show progress)
  -i, --input-file <FILE>     Read URLs from file (one per line)
  -H, --header <HEADER>       Custom header
      --user-agent <UA>       User agent string
      --referer <URL>         Referer URL
      --cookie <COOKIE>       Cookie
      --checksum <HASH>       Expected checksum
  -x, --max-connections <N>   Max connections
      --max-speed <SPEED>     Max download speed
      --sequential            Sequential mode (torrents)
      --select-files <IDX>    Select files (torrents)
      --seed-ratio <RATIO>    Seed ratio (torrents)

gosh list

List all downloads.

gosh list [OPTIONS]

Options:
  -s, --state <STATE>   Filter by state [active, waiting, paused, completed, error]
      --ids-only        Show only download IDs

gosh status

Show detailed status of a download.

gosh status [OPTIONS] <ID>

Options:
      --peers   Show peer information (torrents)
      --files   Show file list (torrents)

gosh pause

Pause one or more downloads.

gosh pause <ID>...
gosh pause all    # Pause all active downloads

gosh resume

Resume paused downloads.

gosh resume <ID>...
gosh resume all   # Resume all paused downloads

gosh cancel

Cancel and optionally delete downloads.

gosh cancel [OPTIONS] <ID>...

Options:
      --delete   Also delete downloaded files
  -y, --yes      Skip confirmation prompt

gosh priority

Set download priority.

gosh priority <ID> <PRIORITY>

Priorities: low, normal, high, critical

gosh stats

Show global download/upload statistics.

gosh stats

Output:

Global Statistics
=================

Downloads:
  Active:   2
  Waiting:  5
  Stopped:  10
  Total:    17

Speed:
  Download: 5.2 MB/s
  Upload:   1.1 MB/s

gosh info

Parse and display torrent file information.

gosh info <TORRENT_FILE>

gosh config

Manage configuration.

gosh config show              # Show current config
gosh config path              # Show config file path
gosh config get <KEY>         # Get a config value
gosh config set <KEY> <VALUE> # Set a config value

Global Options

These options can be used with any command:

Configuration

Configuration file location: ~/.config/gosh/config.toml

[general]
download_dir = "~/Downloads"
log_level = "warn"

[engine]
max_concurrent_downloads = 5
max_connections_per_download = 16
global_download_limit = 0      # 0 = unlimited
global_upload_limit = 0

# BitTorrent settings
enable_dht = true
enable_pex = true
enable_lpd = true
max_peers = 55
seed_ratio = 1.0

# HTTP settings
user_agent = "gosh/0.1"
connect_timeout = 30
read_timeout = 60

[tui]
refresh_rate_ms = 250
theme = "dark"                 # or "light"
show_speed_graph = true

Exit Codes

Comparison with aria2

gosh provides aria2-style command-line usage while offering a native Rust implementation:

Examples

Download a File

# Simple download
gosh https://example.com/file.zip

# Download to specific directory
gosh -d ~/Downloads https://example.com/file.zip

# Download with custom filename
gosh -o myfile.zip https://example.com/file.zip

Batch Downloads

# Multiple URLs
gosh https://example.com/file1.zip https://example.com/file2.zip

# From file
gosh add -i urls.txt

# Pipe from stdin
cat urls.txt | gosh add -

BitTorrent

# Magnet link
gosh "magnet:?xt=urn:btih:..."

# Torrent file
gosh ubuntu-24.04.torrent

# Select specific files
gosh --select-files 0,1,2 multi-file.torrent

# Sequential for streaming
gosh --sequential movie.torrent

Scripting

# JSON output for parsing
gosh list --output json | jq '.[] | .id'

# Check download status
if gosh status abc123 --output json | jq -e '.state == "Completed"'; then
  echo "Download finished!"
fi

# Monitor progress
gosh add -w https://example.com/large-file.iso

Building from Source

# Development build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Run with verbose logging
RUST_LOG=debug cargo run -- https://example.com/file.zip

Requirements

• Rust 1.75+ (for async trait support)
• Linux, macOS, or Windows

License

MIT License - see LICENSE for details.

Related Projects

• gosh-dl - The underlying download engine library
• docs.rs/gosh-dl-cli - API documentation