gosh-dl-cli

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:

Flag	Description
-c, --config <PATH>	Config file path (env: GOSH_CONFIG)
-v, --verbose	Increase log verbosity (-v, -vv, -vvv)
-q, --quiet	Suppress output except errors
--output <FORMAT>	Output format: table, json, json-pretty
--color <WHEN>	Color output: auto, always, never
--proxy <URL>	Proxy URL (http://, https://, socks5://)
--max-retries <N>	Max retry attempts for failed downloads

Direct mode options

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

Flag	Description
-d, --dir <PATH>	Output directory
-o, --out <NAME>	Output filename (single download only)
-x, --max-connections <N>	Connections per download (default: 8)
--max-speed <SPEED>	Speed limit (supports K/M/G suffixes)
-H, --header <HEADER>	Custom header ("Name: Value")
--user-agent <UA>	User agent string
--referer <URL>	Referer URL
--cookie <COOKIE>	Cookie ("name=value")
--checksum <HASH>	Verify checksum (md5:... or sha256:...)
--sequential	Download pieces in order (torrents)
--select-files <IDX>	Download specific files (comma-separated, torrents)
--seed-ratio <RATIO>	Stop seeding after this ratio (torrents)
--no-dht	Disable DHT
--no-pex	Disable Peer Exchange
--no-lpd	Disable Local Peer Discovery
--max-peers <N>	Max peers per torrent

Subcommands

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

Accepts all the direct mode options above, plus:

Flag	Description
-p, --priority <LEVEL>	low, normal, high, critical
-w, --wait	Block until download completes
-i, --input-file <FILE>	Read URLs from a file (one per line)

gosh list -- List all downloads.

Flag	Description
-s, --state <STATE>	Filter: active, waiting, paused, completed, error
--ids-only	Print only download IDs

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

Flag	Description
--peers	Show peer info (torrents)
--files	Show file list (torrents)

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.

Flag	Description
--delete	Also delete downloaded files
-y, --yes	Skip confirmation

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

Key	Action
a	Add new download
p	Pause selected
r	Resume selected
c	Cancel selected
d	Cancel and delete files
1 / 2 / 3	View all / active / completed
j/k or arrows	Navigate
PgUp / PgDn	Scroll page
?	Toggle help overlay
q or Ctrl+C	Quit

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

Variable	Description
GOSH_CONFIG	Custom config file path
NO_COLOR	Disable colored output (any value)
HTTPS_PROXY	HTTPS proxy URL
HTTP_PROXY	HTTP proxy URL
ALL_PROXY	Fallback proxy URL
RUST_LOG	Override log level filter

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

Exit codes

Code	Meaning
0	All downloads completed
1	Some downloads failed
2	All downloads failed
130	Interrupted (Ctrl+C)

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.