Iskra

A safe, modern, Rust-native data transfer tool.

Iskra is a security-first, async-capable command-line and library tool for HTTP and data transfer. It aims to be a minimal, idiomatic, and robust alternative to cURL and HTTPie, with a user-friendly CLI and advanced features for modern workflows.

Benchmarks

The following table shows Iskra's download performance (MB/s) for various file sizes and cache scenarios, measured on a local HTTP server and local disk. Each value is the best observed MB/s for that scenario (higher is better).

• No Cache: Downloaded directly from the local HTTP server, no cache used.
• Cold Cache: First download with cache enabled (writes to cache and file).
• Warm Cache: Second/third download with cache enabled (reads from cache).

Test setup:

• Local HTTP server (Rust, hyper)
• Local disk cache (default temp dir)
• Windows, Rust async, single-threaded test
• Each file is validated for integrity (first, middle, last byte)

Note: In some cases, "no cache" can be faster than "cold cache" or even "warm cache". This is because writing to both the output file and the cache file doubles disk I/O, and the OS may cache files in memory, making repeated reads or writes appear faster. For real-world remote transfers, or with a RAM disk, cache can provide a more significant speedup.

Usage

Installation

1. Install with Cargo (recommended):

   • Open a terminal (PowerShell, Command Prompt, or Bash).

   • To install the latest published version:

     cargo install iskra
     

   • To build and install from source (in the repo root):

     cargo install --path .
     

   • If you don't have Rust or Cargo, install them first from https://rustup.rs

2. Add to PATH:

   • Make sure the Cargo bin directory is in your system PATH so you can run iskra from anywhere:

     • Windows: %USERPROFILE%\.cargo\bin

     • Linux/macOS: $HOME/.cargo/bin

   • If you just installed Rust, you may need to restart your terminal or log out/in for the new PATH to take effect.

   • To update your PATH for the current session only:

     • PowerShell:

       $env:Path += ";$env:USERPROFILE\.cargo\bin"
       

     • Bash:

       export PATH="$HOME/.cargo/bin:$PATH"
       
       

3. Test your install:

   iskra --help
   

   If you see the help text, you're ready to go!

   The help command shows all available commands, options, and usage examples. For more details on a specific command, you can run:

   iskra <command> --help
   

   For example:

   iskra post --help
   

   This will display all options and usage for the post command. Use --help with any command to see its arguments and flags.

Troubleshooting:

• If iskra is not found, double-check your PATH and that the install completed successfully.
• On Windows, you may need to open a new terminal or restart your computer after changing PATH.
• If you see a permissions error, try running your terminal as administrator (Windows) or use sudo (Linux/macOS) for the install step.

Updating Iskra

To update Iskra to the latest published version from crates.io, run:

PowerShell/Windows:

cargo install iskra --force

Bash/Linux/macOS:

cargo install iskra --force

This will overwrite any previous version with the latest release. You can check your installed version with:

iskra --version

or

iskra --version

If you build from source (Git):

First, update your local repository:

git pull

Then rebuild and install:

cargo install --path . --force

This will install the latest code from your local repository. Again, check your version with:

iskra --version

Why Iskra?

Why choose Iskra?

• Security-first: Strict error handling, no unsafe code, validation for all edge cases.
• Performance: Async, streaming, and range-aware downloads for maximum speed and efficiency.
• Resumable & partial downloads: Advanced file-based cache with metadata, HTTP headers, and range support.
• Minimal dependencies: Small, modern Rust async stack.
• Cross-platform: Windows, Linux, macOS.
• User-friendly CLI: Intuitive, scriptable, and easy to use in any shell.
• Production-grade tests: All features are covered by stringent tests.
• Supports GET, POST, PUT, DELETE, and arbitrary HTTP methods (e.g. PATCH, OPTIONS), with custom headers, query parameters, output to file, status/exit code support, and configurable timeout.
• Advanced file-based cache, streaming writes, cache validation and reconstruction, overwrite/append/chunked/partial download support, automatic response decompression, progress bar, and more.

If you want a modern, safe, and fast HTTP tool that feels at home in your shell, Iskra is for you.

Command Overview

Iskra supports the following commands:

GET (default)

iskra get <url> [OPTIONS]
iskra <url> [OPTIONS]  # 'get' is the default command

POST

iskra post <url> [--body <data>] [OPTIONS]

PUT

iskra put <url> [--body <data>] [OPTIONS]

DELETE

iskra delete <url> [OPTIONS]

Custom HTTP Method

iskra custom --method <METHOD> <url> [--body <data>] [OPTIONS]

Common Options

Examples

1. Install with Cargo (recommended):

   • Open a terminal (PowerShell, Command Prompt, or Bash).

   • To install the latest published version:

     cargo install iskra
     

   • To build and install from source (in the repo root):

     cargo install --path .
     

   • If you don't have Rust or Cargo, install them first from https://rustup.rs

2. Add to PATH:

   • Make sure the Cargo bin directory is in your system PATH so you can run iskra from anywhere:

     • Windows: %USERPROFILE%\.cargo\bin
     • Linux/macOS: $HOME/.cargo/bin

   • If you just installed Rust, you may need to restart your terminal or log out/in for the new PATH to take effect.

   • To update your PATH for the current session only:

     • PowerShell:

       $env:Path += ";$env:USERPROFILE\.cargo\bin"
       

     • Bash:

       export PATH="$HOME/.cargo/bin:$PATH"
       
       

3. Test your install:

   iskra --help
   

   If you see the help text, you're ready to go!

   The help command shows all available commands, options, and usage examples. For more details on a specific command, you can run:

   iskra <command> --help
   

   For example:

   iskra post --help
   

   This will display all options and usage for the post command. Use --help with any command to see its arguments and flags.

   Set-Alias iskra "$env:USERPROFILE\.cargo\bin\iskra.exe"
   

• Bash (Linux/macOS):

  • Add to your .bashrc or .zshrc:

     export PATH="$HOME/.cargo/bin:$PATH"
    
     alias iskra="$HOME/.cargo/bin/iskra"
    
    

• Command Prompt (cmd.exe):

  • Add %USERPROFILE%\.cargo\bin to your system PATH via System Properties.

For more details, see iskra --help or the source code in src/cli.rs.

Licence

MIT OR Apache-2.0