aria2s turns aria2c into an always-on download service with a terminal dashboard to manage downloads.
One-liner (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/amio/aria2s/main/install.sh | shOr if you have Go installed
go install github.com/amio/aria2s@latestaria2s uninstall # remove the registered background service
rm "$(command -v aria2s)" # remove the binaryaria2s install --start # install & launch the background service
aria2s dashboard # open the interactive terminal dashboard to manage downloadsor simply:
aria2s # ensure install/start, open the terminal dashboard| Command | What it does |
|---|---|
aria2s |
Daily entrypoint: ensure the service is installed and running, open the full-screen dashboard. |
aria2s install [--start] |
Set up aria2c as a background service through launchd on macOS or systemd --user on Linux. Re-running it reasserts the managed service state and writes a default ~/.aria2/aria2.conf only when that file is missing. |
aria2s uninstall |
Remove the registered background service. |
aria2s start / stop / restart |
Control the background service. start returns immediately when the service is already healthy. Stop & restart save the session first. |
aria2s status |
Show service state, port, version, and log paths at a glance. |
aria2s doctor |
Check for common issues (missing binary, port conflicts, unloaded or stopped supervisor). |
aria2s logs |
Print recent log output. |
aria2s add <url-or-magnet> |
Submit a download via RPC — no need to remember the port or token. |
aria2s dashboard |
Explicit dashboard entrypoint. Uses the same auto-install and auto-start readiness flow as bare aria2s. |
aria2s is a thin wrapper around aria2c: user-tuned download settings live in ~/.aria2/aria2.conf, while the managed RPC and session flags are passed to aria2c through the service definition.
make build # build
make test # run all testsDashboard runtime and shortcut-key migration notes live in docs/implemented/bubbletea-v2-upgrade.md.
Smoke-test in an isolated environment:
Linux note: service startup still needs a live
systemd --usersession even whenHOMEis overridden for an isolated test directory.
TMP_HOME=$(mktemp -d)
HOME="$TMP_HOME" ./bin/aria2s install --start
HOME="$TMP_HOME" ./bin/aria2s status
HOME="$TMP_HOME" ./bin/aria2s add https://example.com/file.zip
HOME="$TMP_HOME" ./bin/aria2s uninstall
rm -rf "$TMP_HOME"MIT