Command Reference
Detailed reference for all Risuko CLI commands.
download
Download a file from a URL, magnet link, or local .torrent file.
risuko download <url>... [options]If no running engine is detected, a temporary headless instance is started automatically and stopped when the download finishes.
The command waits until the task ends. It exits 0 on completion, or 1 with Download failed: <message> or Download was removed. If seeding is configured (--seed-ratio, --seed-time, or keep-seeding), a torrent stays active until its seeding goal is met, so the command blocks until then. With --json it prints one JSON status object per line every 500 ms instead of a progress bar.
Arguments
| Argument | Description |
|---|---|
url... | URL(s), a magnet link, or a path to a .torrent file. Multiple URLs are treated as HTTP mirrors of the same file. The CLI rejects extra inputs alongside a local .torrent file, a media-host URL, or --ytdlp; if a magnet is mixed with other URLs, the engine keeps only the magnet. A .torrent is detected only when the path ends in .torrent and exists locally; a remote .torrent URL downloads as a plain file |
Options
| Option | Short | Default | Description |
|---|---|---|---|
--threads | -t | 16 | Number of connections per download |
--dir | -d | — | Download directory |
--out | -o | — | Output filename |
--header | -H | — | HTTP header (repeatable) |
--user-agent | — | — | User agent string |
--proxy | — | — | Proxy server URL |
--referer | — | — | HTTP referer |
--cookie | — | — | Cookie string, sent as a Cookie header (ignored if a -H header already sets one) |
--media-format | — | — | Media format selector passed to yt-dlp (alias: --youtube-format) |
--ytdlp | — | — | Force the URL through the yt-dlp media engine even if its host is not in the built-in allowlist |
--seed-ratio | — | — | BitTorrent seed ratio (e.g. 1.0) |
--seed-time | — | — | BitTorrent seed time in minutes |
--rpc-port | — | 16800 | RPC port to connect to |
--rpc-secret | — | — | RPC authentication token |
--json | — | — | Output as JSON |
Examples
# Basic HTTP download
risuko download https://example.com/file.zip
# With 32 connections to a specific directory
risuko download https://example.com/file.zip -t 32 -d ~/Downloads
# Torrent with seeding limits
risuko download ./ubuntu-24.04.torrent --seed-ratio 1.0 --seed-time 60
# With authentication header
risuko download https://example.com/private.zip -H "Authorization: Bearer token"
# Media download via yt-dlp with a format selector
risuko download https://example.com/watch?v=abc --ytdlp --media-format "bestvideo+bestaudio"
# From a .torrent file
risuko download ./ubuntu-24.04.torrent -d ~/Downloadsstatus
Show status of active, waiting, and stopped downloads.
risuko status [options]Options
| Option | Default | Description |
|---|---|---|
--gid | — | Show a specific task by GID |
--rpc-port | 16800 | RPC port to connect to |
--rpc-secret | — | RPC authentication token |
--json | — | Output as JSON |
Output
Without --gid, displays a table of all downloads:
GID Status Name Progress Speed Size
---------------------------------------------------------------------------------------------
a1b2c3d4e5f6a7b8 active ubuntu-24.04-server-amd64.iso 64.2% 12.4 MB/s 2.6 GB
e5f6a7b8c9d0e1f2 waiting archlinux-2024.04.01-x86_... 0.0% - 1.2 GB
c9d0e1f2a1b2c3d4 complete node-v22.0.0.tar.gz 100.0% - 89.4 MBThe table lists all active tasks plus at most 100 waiting and 100 stopped tasks.
With --gid, shows detailed information for a single task.
pause
Pause a specific download.
risuko pause <gid> [--rpc-port PORT] [--rpc-secret SECRET]resume
Resume a paused download.
risuko resume <gid> [--rpc-port PORT] [--rpc-secret SECRET]remove
Remove one or more downloads from the engine. Active downloads are stopped first.
risuko remove <gid>... [--rpc-port PORT] [--rpc-secret SECRET]Multiple GIDs can be passed in a single invocation.
pause-all
Pause all active downloads.
risuko pause-all [--rpc-port PORT] [--rpc-secret SECRET]resume-all
Resume all paused downloads.
risuko resume-all [--rpc-port PORT] [--rpc-secret SECRET]global-stat
Show global download and upload statistics.
risuko global-stat [--rpc-port PORT] [--rpc-secret SECRET] [--json]Output
Download: 24.8 MB/s Upload: 1.2 MB/s
Active: 3 Waiting: 2 Stopped: 15Waiting is the engine's broad not-active-yet bucket: waiting, paused, and
scheduled tasks are all counted there.
files
Show files belonging to a download.
risuko files <gid> [--rpc-port PORT] [--rpc-secret SECRET] [--json]peers
Show connected peers for a BitTorrent download.
risuko peers <gid> [--rpc-port PORT] [--rpc-secret SECRET] [--json]purge
Remove completed, errored, and removed download results from the engine's memory.
risuko purge [--rpc-port PORT] [--rpc-secret SECRET]config
Manage engine configuration. Configuration is stored as JSON files (system.json and user.json) in <OS config dir>/app.risuko.Risuko (or the legacy dev.risuko.app when that directory already exists; see Config Directory Locations). These commands edit the files directly and do not talk to a running engine.
config get
risuko config get <key>Prints the value from user.json layered over system.json. An unknown key prints Key '<key>' not found and exits 0.
config set
risuko config set <key> <value>The value is parsed as JSON; if parsing fails, it is stored as a plain string. Writes always go to user.json.
The engine (serve, the temporary engine started by download, and the Node.js API) reads only user-scope keys from user.json (such as rpc-host, keep-seeding, bt-*, pbh-*, and proxy) plus the engine-overrides object. Engine keys such as dir, max-concurrent-downloads, split, doh-*, and rpc-secret are read from system.json only, so config set dir … has no effect even though config get and config list show the new value.
To change engine keys from the CLI, write them into engine-overrides. This replaces the whole object, and rpc-*, *-port, and *-secret keys inside it are ignored:
risuko config set engine-overrides '{"dir":"/home/user/downloads","max-concurrent-downloads":8}'For rpc-secret and ports, edit system.json directly.
config list
risuko config list [--json]rss
Manage RSS feed subscriptions.
The RSS CLI commands call RPC methods (risuko.addRssFeed, risuko.getRssFeeds, risuko.refreshAllRssFeeds, risuko.removeRssFeed) that are not yet implemented in the engine's RPC server. These commands will currently return a "method not found" error. RSS management is available directly in the desktop app.
rss add
risuko rss add <url> [--rpc-port PORT] [--rpc-secret SECRET]rss list
risuko rss list [--rpc-port PORT] [--rpc-secret SECRET] [--json]rss refresh
Refresh all RSS feeds and trigger new downloads.
risuko rss refresh [--rpc-port PORT] [--rpc-secret SECRET]rss remove
risuko rss remove <id> [--rpc-port PORT] [--rpc-secret SECRET]serve
Start the engine in headless mode (RPC server only, no GUI).
risuko serve [--rpc-port PORT] [--verbose]The engine runs until interrupted (Ctrl+C) or a shutdown command is received.
| Option | Short | Default | Description |
|---|---|---|---|
--rpc-port | — | 16800 | RPC listen port |
--verbose | -v | false | Set the log level to debug,risuko_engine=trace (default info); RUST_LOG overrides it |
There is no --rpc-secret flag for serve; the RPC secret comes from the rpc-secret key in system.json. The optional PeerBanHelper listener (pbh-enable, pbh-listen-port, pbh-rpc-secret) is also read from config and started alongside the primary RPC when enabled.
shutdown
Request the engine to shut down via RPC.
risuko shutdown [--rpc-port PORT] [--rpc-secret SECRET]