# gosh
A download manager for the terminal. HTTP/HTTPS with multi-connection acceleration, full BitTorrent support, and an optional TUI. Built on [gosh-dl](https://github.com/goshitsarch-eng/gosh-dl).
## Install
From source (requires Rust 1.85+):
```bash
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:
```bash
cargo install gosh-dl-cli
```
Without the TUI (smaller binary, fewer dependencies):
```bash
cargo install gosh-dl-cli --no-default-features
```
Pre-built binaries are available on [GitHub Releases](https://github.com/goshitsarch-eng/gosh-dl-cli/releases). Linux builds are statically linked with musl.
## Quick start
Download a file:
```bash
gosh https://example.com/file.zip
```
Download to a specific directory with a custom filename:
```bash
gosh -d ~/Downloads -o archive.zip https://example.com/file.zip
```
Multiple files at once:
```bash
gosh https://example.com/a.zip https://example.com/b.zip
```
Torrents and magnet links work the same way:
```bash
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:
| `-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>...`):
| `-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:
| `-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.
| `-s, --state <STATE>` | Filter: `active`, `waiting`, `paused`, `completed`, `error` |
| `--ids-only` | Print only download IDs |
**`gosh status <ID>`** -- Show detailed status of a download.
| `--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.
| `--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
| `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.
```toml
[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
| `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
| 0 | All downloads completed |
| 1 | Some downloads failed |
| 2 | All downloads failed |
| 130 | Interrupted (Ctrl+C) |
## Building from source
```bash
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](LICENSE).