arkama

Very, very, very, work in progress, proceed with fire!

Fast, practical download manager. Ships as arkama-cli and the combined arkama binary.

🧭 Quick start (CLI)

arkama-cli download <url>
arkama-cli download <url> -o ./file.bin
arkama-cli download <url> --connections 8
arkama-cli daemon start
arkama-cli add <url>
arkama-cli list
arkama-cli pause <job-id>
arkama-cli resume <job-id>

You can replace arkama-cli with arkama in the examples below if you prefer the combined binary.

✨ Features

CLI-first for now.

• HTTP/HTTPS downloads with redirects.
• Filename inference from Content-Disposition or URL path.
• Resume via HTTP Range.
• Segmented downloads when size and range support are available (default 4 connections).
• Falls back to single stream when Range is unavailable.
• Progress bar with total bytes, speed, and ETA.
• Retries with exponential backoff on transient failures.
• Ctrl+C saves state for resume.
• Optional global speed limit.
• Experimental connection entropy mode for LACP/ECMP environments.
• Download history backed by SQLite.
• Background daemon with local TCP control and persisted queue recovery.
• Daemon job control: add, list, show, pause, resume, cancel, and retry.
• Resume validation with ETag/Last-Modified metadata and If-Range for range requests.
• Search across past downloads.
• Configurable download folder (persisted in app settings).
• JSON output for automation.

🔄 Shared configuration

Both binaries share the same SQLite database for settings and download history:

# Set download folder (used by both binaries)
arkama-cli config set download_dir ~/Downloads
arkama-cli config set connections 8
arkama-cli config set speed_limit 2MB

# View current config
arkama-cli config show

# View download history
arkama-cli history
arkama-cli history -n 50
arkama-cli history -q "example.com"

🎛️ CLI commands

arkama-cli download [OPTIONS] [URL]

Download a file from a URL.

• -o, --output <PATH>: output file path.
• --links-file <PATH>: text file with one URL per line (downloads run sequentially).
• --connections <N>: concurrent connections for segmented downloads (defaults to config, otherwise 4).
• --user-agent <UA>: override HTTP User-Agent.
• --limit <BYTES_PER_SEC>: global speed limit (defaults to config if unset; ex: 2MB, 500KB).
• --experimental-entropy: experimental; disables idle pooling, uses 4MB segments, and recycles slow segment connections.
• --daemon: enqueue the download on the local arkama daemon.
• --silent: suppress progress and summary output.
• --json: emit JSON events to stdout for automation.

arkama-cli daemon <COMMAND>

Manage the background daemon.

• arkama-cli daemon start: launch the daemon in the background.
• arkama-cli daemon run: run the daemon in the foreground.
• arkama-cli daemon status: show daemon status.
• arkama-cli daemon stop: stop the daemon.

Queued daemon jobs are stored in the shared SQLite database, survive daemon restarts, and are recovered automatically when the daemon starts again.

Daemon job commands

These commands operate on the running daemon:

• arkama-cli add <url>: add a download job to the daemon.
• arkama-cli list [-n <N>] [-q <QUERY>]: list recent jobs.
• arkama-cli show <job-id>: show job details.
• arkama-cli pause <job-id>: pause an active or queued job.
• arkama-cli resume <job-id>: resume a paused job.
• arkama-cli cancel <job-id>: cancel an active, queued, or paused job.
• arkama-cli retry <job-id>: retry a failed or cancelled daemon job.

arkama-cli history [OPTIONS]

Show download history.

• -n, --limit <N>: number of records to show (default 20).
• -q, --query <QUERY>: filter by URL, path, or status.

arkama-cli config <COMMAND>

View or modify configuration.

• arkama-cli config show: show all settings.
• arkama-cli config get <KEY>: get a setting value.
• arkama-cli config set <KEY> <VALUE>: set a setting value.

Common keys:

• download_dir
• connections
• max_concurrent
• speed_limit

arkama <COMMAND>

The arkama binary exposes the same CLI commands as arkama-cli.

Global options

• --reset-db: reset the application database.

🧪 Experimental entropy mode

--experimental-entropy is for bonded network setups that load-balance by hashing the 5‑tuple (LACP/ECMP). It pushes connection diversity so traffic spreads across links.

What changes:

• Disables idle pooling so segments prefer fresh connections.
• Uses fixed 4MB segments across your --connections worker count.
• Recycles slow segment connections for the remaining bytes.

Tradeoffs:

• More connection churn and TCP/TLS handshakes.
• Slightly higher CPU and latency overhead.
• Can be slower on small files or servers with strict connection limits.

Resume notes:

• Resume state includes the segment size and entropy mode flag.
• If you resume without the same entropy setting, arkama starts fresh instead of reusing incompatible state.

Should I use this? Nope.

💾 Resume and state

• If the output file exists, arkama resumes when possible.
• For segmented downloads, state is stored in *.arkama.state next to the output file.
• On successful completion, the state file is removed.

📌 Examples

# Download files
arkama-cli download https://example.com/file
arkama-cli download https://example.com/file -o ./file.bin
arkama-cli download https://example.com/file --connections 8
arkama-cli download https://example.com/file --limit 2MB
arkama-cli download --links-file ./links.txt
arkama-cli download https://example.com/file --experimental-entropy
arkama-cli daemon start
arkama-cli download https://example.com/file --daemon
arkama-cli download https://example.com/file --silent
arkama-cli download https://example.com/file --json

# Configuration and history
arkama-cli config show
arkama-cli config set download_dir ~/Downloads
arkama-cli history
arkama-cli history -n 10 -q "zip"