fURL (furl-cli)

A fast, multithreaded CLI downloader built in Rust.

furl is a high-performance command-line tool designed to download files faster by utilizing multiple threads to fetch chunks of data concurrently. Inspired by the simplicity of cURL and the robustness of wget.

Warning

This branch is usually ahead of the latest release. If something does not work as expected, consider checking out a specific release tag, or install a stable version via cargo or winget. For more, see the Installation section.

✨ Features

• Smart Parallel Downloads: Automatically splits large files into chunks and downloads them across multiple threads when needed and size is known. Also automatically shrinks the maximum length of chunk to 10MB for better resource utilization.
• Modern Async: Built on top of tokio and reqwest for maximum efficiency.
• Visual Progress: Beautiful, real-time progress bars using indicatif.
• Rust Powered: Memory-safe and "fearless" concurrency.

Installation

You can install furl using the install script, WinGet, Cargo, or by building it from source.

Quick Install (Linux, macOS, Windows)

The install script downloads the right pre-built binary for your OS/architecture from the latest release and puts it on your PATH. No Rust toolchain required.

Linux / macOS:

curl -LsSf https://raw.githubusercontent.com/ghimiresdp/furl-cli/main/scripts/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/ghimiresdp/furl-cli/main/scripts/install.ps1 | iex"

Windows (Recommended: WinGet)

For Windows users, WinGet is the recommended installation method. Requirement: WinGet must be available on your system (included by default on modern Windows 10/11 setups).

winget install ghimiresdp.furl

Crates.io

Use this method on any platform where Rust is installed. Requirement: Rust toolchain and Cargo must be installed. Install Rust from the official guide: https://www.rust-lang.org/tools/install

cargo install furl-cli

From Source

Use this method if you want to build from the latest source code or contribute changes. Requirement: Git, Rust toolchain, and Cargo must be installed. Install Rust from the official guide: https://www.rust-lang.org/tools/install

git clone https://github.com/ghimiresdp/furl-cli.git
cd furl-cli
cargo build --release

Pre-built Binaries

The Quick Install script above is the easiest way to get a pre-built binary. If you'd rather install one by hand (or need a platform the script doesn't cover), download it from the Assets section of the latest release.

If you need an older version, browse all published releases in the Releases section and check the Assets section for that release.

🛠 Usage

furl can be used in 2 modes Library mode and Binary mode.

Binary Mode

You need to install the furl-cli and add it to the path before you can use it in the binary mode. For more details, you can check the Installation section.

Without output directory

When no output directory is passed, it automatically downloads the file in the current terminal directory (PWD).

furl [URL]

Example:

furl https://raw.githubusercontent.com/ghimiresdp/furl-cli/refs/heads/main/res/images/example.png

With output directory

furl [URL] -o [path/to/the/directory]

Example:

furl https://raw.githubusercontent.com/ghimiresdp/furl-cli/refs/heads/main/res/images/example.png -o ./tmp -t 32

Configuration

furl reads defaults for download_dir, threads, and max_chunk_size from a config file at ~/.config/.furl/config.toml (path varies by OS; resolved via dirs::config_dir()). The file is created with built-in defaults the first time furl runs, with each key preceded by a comment explaining what it does, so it's safe to open and hand-edit. Any --out, --threads, or --chunksize flag you pass on the command line overrides the config file for that run only. --chunksize/-c accepts the same format as max_chunk_size below: a plain byte count, or a human-readable size (512KB, 5MB, 1GB).

Manage it with the furl config subcommand:

# list every value
furl config

# read a single value
furl config threads

# set and save a value
furl config threads 16

# max_chunk_size accepts a human-readable size (B, KB, MB, GB, TB) or a
# plain byte count
furl config max_chunk_size 5MB

# restore the built-in defaults
furl config --reset

Library Mode

In library mode, you can just import the Downloader struct and use its download() method to download files.

use furl_core::{DownloadConfig, Downloader};

// since Downloader::download() method is async, it needs to be implemented
// inside the async function. if it is main function, we can use
// `#[tokio::main]` macro.
#[tokio::main]
async fn main() {
    let url = "https://raw.githubusercontent.com/ghimiresdp/furl-cli/refs/heads/main/res/images/example.png";

    let config = DownloadConfig::default().set_max_chunk_size(5 * 1024 * 1024); // 5 MB

    let mut downloader = Downloader::new(url).with_config(config);

    if downloader.download(".", None, Some(4)).await.is_ok() {
        println!("Download completed successfully!");
    } else {
        println!("Download failed.");
    }
}

For runnable workspace examples that embed furl-cli as a library, check the examples/ directory (e.g. embedded-minimal, no-indicator).

🏗 Architecture Decisions

Project design decisions are documented as Architecture Decision Records (ADRs) under docs/adr. The ADR index is available at docs/adr/README.md.

📦 Examples

Implementation-oriented examples live in the examples directory. These are standalone workspace crates that show how to use furl-cli as a library in real applications.

🗺 Roadmap

• Multithreaded chunk downloading
• Customize number of threads with arguments
• Basic CLI argument parsing (clap)
• Real-time progress bars
• Smart Threading (Completely ignore threading for files smaller than 1 MB).
• Package manager support (Windows: WinGet)
• Examples
• Config file support (~/.config/.furl/config.toml)
• Support for Proxy and Basic Auth
• Resume interrupted downloads (Checkpoints)
• Package manager support (Linux: APT)
• Package manager support (Linux: Flatpak)
• Package manager support (Linux: Snap)
• Package manager support (macOS: Homebrew)

🤝 Contributing

Contributions are welcome! Since this project is actively being developed, please open an issue first to discuss the changes you'd like to make.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')`
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For more details, please check CONTRIBUTING.md.

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Third-Party Licenses

This software uses several open-source components. You can view the full list of dependencies and their licenses using cargo-license:

Note

furl-cli (or fURL) is a successor to my previous project ghimiresdp/rust-raid's cget download manager. It incorporates refined logic and improved multithreading from that original implementation.