gosh

A download manager for the terminal. HTTP/HTTPS with multi-connection acceleration, full BitTorrent support, and an optional TUI. Built on gosh-dl.

Install

From source (requires Rust 1.85+):

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

From crates.io:

cargo install gosh-dl-cli

Without the TUI (smaller binary, fewer dependencies):

cargo install gosh-dl-cli --no-default-features

Pre-built binaries are available on GitHub Releases. Linux builds are statically linked with musl.

Quick start

Download a file:

gosh https://example.com/file.zip

Download to a specific directory with a custom filename:

gosh -d ~/Downloads -o archive.zip https://example.com/file.zip

Multiple files at once:

gosh https://example.com/a.zip https://example.com/b.zip

Torrents and magnet links work the same way:

gosh magnet:?xt=urn:btih:...
gosh ./ubuntu.torrent

Launch the interactive TUI by running gosh with no arguments.

Usage modes

gosh has three modes:

Direct mode -- pass URLs as arguments and downloads start immediately with progress bars. This is the aria2-style workflow most people want.

TUI mode -- run gosh with no arguments for a full-screen terminal interface. You can add, pause, resume, and monitor downloads interactively.

Command mode -- use subcommands (gosh add, gosh list, etc.) for scripting and automation.

CLI reference

Global options

These work with any mode or subcommand:

Direct mode options

Used when passing URLs directly (gosh [OPTIONS] <URL>...):

Subcommands

gosh add <URL>... -- Add downloads to the queue.

Accepts all the direct mode options above, plus:

gosh list -- List all downloads.

gosh status <ID> -- Show detailed status of a download.

gosh pause <ID>... -- Pause downloads. Use all to pause everything.

gosh resume <ID>... -- Resume paused downloads. Use all to resume everything.

gosh cancel <ID>... -- Cancel downloads.

gosh priority <ID> <LEVEL> -- Set download priority (low, normal, high, critical).

gosh stats -- Show global download/upload statistics.

gosh info <FILE> -- Parse and display torrent file metadata.

gosh config <ACTION> -- Manage configuration: show, path, get <KEY>, set <KEY> <VALUE>.

gosh completions <SHELL> -- Generate shell completions for bash, zsh, fish, elvish, or powershell. Pipe the output to the appropriate completions directory for your shell.

TUI keyboard shortcuts

The details panel at the bottom shows a speed graph sparkline for the selected download.

Configuration

Config file location: ~/.config/gosh-dl/config.toml

Override the path with -c <PATH> or the GOSH_CONFIG environment variable.

[general]
download_dir = "~/Downloads"
log_level = "info"                      # trace, debug, info, warn, error

[engine]
max_concurrent_downloads = 5
max_connections_per_download = 8
global_download_limit = 0               # bytes/sec, 0 = unlimited
global_upload_limit = 0
max_retries = 3
connect_timeout = 30                    # seconds
read_timeout = 60

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

# Proxy (overridden by --proxy flag or env vars)
# proxy_url = "socks5://127.0.0.1:1080"

# TLS (dangerous -- prefer --insecure flag for one-off use)
# accept_invalid_certs = false

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

# Bandwidth scheduling -- rules are evaluated in order, first match wins
# [[schedule.rules]]
# start_hour = 9
# end_hour = 17
# days = "weekdays"                     # "all", "weekdays", "weekends", or "mon,tue,..."
# download_limit = "2M"                 # K/M/G suffixes
# upload_limit = "512K"

Environment variables

Proxy precedence: --proxy flag > config file > HTTPS_PROXY > HTTP_PROXY > ALL_PROXY.

Exit codes

Building from source

cargo build                     # debug build
cargo build --release           # optimized (LTO + stripped)
cargo test                      # run tests
cargo build --no-default-features --release   # without TUI

Release builds use thin LTO, symbol stripping, and single codegen unit for smaller binaries.

License

MIT -- see LICENSE.