Skip to content

README.en.md

Latest commit

 

History

History
392 lines (263 loc) · 19.8 KB

README.en.md

File metadata and controls

392 lines (263 loc) · 19.8 KB
Raw

ii logo

ii

A cross-platform CLI toolkit for temporary cross-device file movement, LAN sharing, and lightweight network work.

Release License Platforms Rust

简体中文 · English

ii centers on temporary cross-device file movement and adds LAN sharing, short-lived access, and network troubleshooting tools. It is not a cloud drive, long-running NAS, or production proxy platform.

Its core transfer path is ii send / ii recv: no server needs to be deployed first; it prefers LAN or direct Internet P2P connectivity and uses Iroh's default n0 relay only when needed. The receiver only needs the ticket.

Capabilities

Temporary Transfer and Storage Backends

  • Send files, folders, multiple paths, or piped data. Receivers can resume, skip matching MD5 files, and overwrite conflicts.
  • Compute local checksums, preserve single-file metadata, choose symlink behavior, and run FIFO queues or directory watches.
  • When a backend is needed, use generic S3, Cloudflare R2, Azure Blob, WebDAV, FTP, or SFTP, with optional cleanup after receipt.

LAN File and Browser Services

  • Use ii web to share a directory, serve downloads, or accept browser uploads. ii http serves a read-only directory, ii drop is upload-only, and ii paste shares short text.
  • Use ii dav to expose a directory as a WebDAV network drive, or ii ftp for FTP/FTPS compatibility.
  • Use ii webrtc for browser-to-browser file and text transfer on the same LAN. ii discover finds active ii services on the local network.

Temporary Access, Proxies, and Forwarding

  • Use ii tunnel to expose a local TCP service through Iroh; run ii relay only when a fixed relay endpoint is needed.
  • Use ii socks5, ii proxy, and ii pac for proxy access and rule distribution.
  • Use ii tcp and ii udp to forward traffic to a fixed target for short-term integration work or port mapping.

Network Checks and LAN Utilities

  • ii ping, ii port, and ii health check TCP latency, ports, and service health.
  • ii speed measures real LAN throughput, while ii wake sends Wake-on-LAN magic packets.
  • ii test checks SOCKS5, HTTP, or HTTPS proxies in stages: listener, target access, and latency.

Install

Linux x86_64 and Apple Silicon macOS:

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/zengyufei/ii/master/install.sh | bash

The default install path is ~/.local/bin/ii; set II_INSTALL_DIR to choose another directory. For Windows x64, download the executable from GitHub Releases. Releases also provide every published asset and its checksum.

Quick Start

Sender:

ii send .\video.mp4

ii prints a ticket:

ii ticket:
ii1k7v...x9a

on the other computer:
ii recv ii1k7v...x9a

Receiver:

ii recv ii1k7v...x9a

What the sender and receiver look like:

Sender screenshot

Receiver screenshot

Send

Files, Folders, and Multiple Paths

# File
ii send .\report.pdf

# Folder; receives as <output-directory>\my-folder
ii send .\my-folder

# Multiple files or folders; receives as <output-directory>\ii
ii send .\report.pdf .\images .\notes.txt

# Name the multiple-input collection root
ii send .\report.pdf .\images --name release

Multiple paths are packed into one tar stream, so older receivers still handle them as directory tars. Top-level input names must be unique.

Pipes, Filters, and Rate Limits

# Piped input needs an output file name
tar czf - .\project | ii send --name project.tar.gz

# Send matching files only; exclude overrides include
ii send .\project --include "**/*.rs" --exclude "target/**"

# All receivers share an 8 MiB/s total sender limit
ii send .\video.mp4 --rate 8MiB

--include and --exclude are repeatable and match /-separated paths relative to each input folder; they do not apply to --web. --rate accepts bytes/s, KiB, MiB, or GiB, and also limits web downloads and backend sends.

Send Control

# Keep the same ticket available
ii send .\my-folder -t

# Copy the receive command or write it to a file
ii send .\video.mp4 -c
ii send .\video.mp4 -o recv.txt

# JSON Lines for automation
ii send .\video.mp4 --json

# Print a checksum of the bytes being sent
ii send .\video.mp4 --checksum sha256

# Preserve mtime, permissions, and read-only metadata for one file
ii send .\video.mp4 --preserve-metadata

Plain ii send exits after its first successful transfer. -t serves up to 16 receivers concurrently and queues up to 1,000 more in first-in, first-out order. Concurrent receivers share sender bandwidth; retry later when the queue is full. With --json, stdout contains JSON Lines only.

--checksum md5|sha256 computes and prints the local payload checksum. It is not stored in the ticket and is not compared automatically. --preserve-metadata accepts one regular file only and wraps it in the existing tar payload; it rejects stdin and --web, and disables resume and MD5 skip for that send.

Queues and Directory Watches

ii queue .\a.zip .\b.zip
ii queue .\report.pdf --after 10s
ii queue .\folder --every 1h
ii watch .\incoming --interval 2s --stabilize 2s

queue and watch are process-local and non-persistent. They accept --rate, storage backends, relay, --local, --no-relay, --checksum, --preserve-metadata, and --symlinks; they reject -t, -c, -o, --web, and --json. --quic-port <1..65535> fixes the Iroh UDP port for P2P jobs.

Storage Backends

Backend Send command Notes
Generic S3 ii send .\video.mp4 --s3 Configure a compatible endpoint, region, bucket, and path-style mode
Cloudflare R2 ii send .\video.mp4 --r2 Separate R2 configuration with the fixed R2 endpoint
Azure Blob ii send .\video.mp4 --azure Shared Key or Container SAS
WebDAV ii send .\video.mp4 --webdav Supports portable tickets
FTP ii send .\video.mp4 --ftp Plaintext ftp:// only
SFTP ii send .\video.mp4 --sftp Password and private-key authentication

--profile <name> selects a backend configuration. S3, R2, and Azure tickets contain only signed object URLs, so receivers need no local profile. -p writes WebDAV, FTP, or SFTP credentials into the ticket; tickets are not encrypted, so share them only with trusted receivers. -d attempts to delete the backend object after a successful receive. Mounted SMB/NFS directories remain usable as local send paths; native SMB/NFS backends are not provided. See ii.md, ftp.md, and sftp.md for configuration and protocol limits.

Receive

# Choose an output directory
ii recv ii1k7v...x9a -o D:\Downloads

# Write to standard output
ii recv ii1k7v...x9a --stdout > project.tar.gz

# JSON Lines for automation
ii recv ii1k7v...x9a --json

If the network drops halfway, run the same ii recv command again and it continues receiving. If the target file already exists with the same content, it is skipped. If the name matches but the content differs, it is overwritten. ii send and ii recv show progress, speed, and elapsed time; ii recv --trace prints connection stages, the final direct or relay path, and RTT. --stdout cannot be combined with --json.

--checksum md5|sha256 computes the received file or directory tar stream after completion and cannot be combined with --stdout. --quic-port applies only to P2P tickets.

Extended Capabilities

LAN Web Sharing and WebDAV

# Serve one file or folder as a download page
ii send .\video.mp4 --web

# Browse a directory; --upload enables standalone file uploads
ii web .\shared --upload --path .\uploads

# Mount a directory in a file manager; writable by default
ii dav .\shared
ii dav .\shared --read-only
ii dav .\shared --port 8443 --username alice --password secret --tls --domain dav.example.com --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem

ii send --web serves a download page for one file or folder. It exits after the first complete /download response by default; add -t to keep serving until Ctrl+C, and the first concurrent download to finish ends the process. Visiting the page, uploads, and failed downloads do not exit. ii web displays an nginx-style directory listing and serves the current directory when no directory is given. --upload enables multi-file uploads only; their default destination is ./ii/ under the startup directory, while --path <dir> selects another directory. Uploads are written in 1 MiB chunks; after a disconnect or refresh, selecting the same file resumes it. ii dav reads and writes its served directory directly, not the web upload directory.

ii dav --username <username> --password <password> enables HTTP Basic Auth; both options are required together. --password is visible in shell history and process listings, so use it only where that is acceptable. --tls enables HTTPS. Without --cert and --key, ii generates a self-signed certificate valid only for the running process, which clients must explicitly trust. For public access, use a trusted PEM certificate or terminate HTTPS in a reverse proxy and bind ii dav to 127.0.0.1. Without --tls, Basic Auth credentials travel in clear text.

--port 8080 fixes the port, --bind :: listens on IPv6 only, and bare --token generates a path token while --token <value> uses the supplied token. A path token is not account authentication.

ii web --once exits only after the first complete ordinary-file GET 200. HEAD, Range, directory pages, 404 responses, and uploads do not consume the one-shot lifetime, and --once conflicts with --upload.

FTP Server

# Share the current directory; listens on 0.0.0.0:21 by default
ii ftp

# Select a directory, credentials, shared bandwidth, and connection limit
ii ftp .\shared --port 2121 --username alice --password secret --rate 8MiB --max 20

# Explicitly enable active and passive modes; advertise this PASV address and port range
ii ftp .\shared --passive-host 192.168.1.20 --passive-ports 49152-49200

# Disable individual operations
ii ftp .\shared --upload false --delete false --rename false

# Explicit FTPS: TLS is required for both control and data channels; without files ii generates a temporary self-signed certificate
ii ftp .\shared --tls
ii ftp .\shared --tls --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem

# Implicit FTPS: start TLS immediately after connecting; defaults to port 990
ii ftp .\shared --tls --implicit

ii ftp shares the current directory or an existing directory. It defaults to anonymous login, 100 control connections, no rate limit, and allows uploads, downloads, deletion, renames, and directory creation. By default it is active-only and creates no passive data listener. Supplying --passive-ports [start-end] enables active and passive modes together; without a range it uses 49152-65535, and --passive-host requires it. --rate caps the total shared bandwidth of every upload and download connection. --delete false blocks both file and directory deletion, while --download false blocks only RETR; directory listings and metadata remain available. 0.0.0.0 is bind-only; the terminal prints the primary LAN IPv4 FTP URL and other: interface URLs.

--tls enables and requires FTPS. Its default is explicit mode: the client receives the plain FTP greeting and then sends AUTH TLS, and the default port remains 21. Without --cert and --key, ii generates a self-signed certificate for the current process and the client must accept it. Existing PEM certificate chains and private keys must be supplied together. --implicit requires --tls; it performs the TLS handshake immediately on connection and defaults to port 990 when --port is omitted. --port 990 alone does not select implicit mode. -k is not an FTP server option.

Lightweight LAN Services

# Read-only directory site with browsing, Range, media playback, and downloads
ii http .\public

# Text clipboard; without text, reads stdin; raw returns plain text
ii paste "meeting code: 123456" --ttl 30m
Get-Content .\note.txt -Raw | ii paste --token

# Upload-only drop box; defaults to .\ii\ under the startup directory
ii drop .\incoming

# Host a PAC file for an existing HTTP or SOCKS5 proxy
ii pac --proxy socks5://192.168.1.10:1080

# LAN throughput server and client
ii speed serve --port 9000
ii speed http://192.168.1.10:9000/ --duration 15s

ii http has no upload or write endpoint. ii drop provides resumable multi-file uploads only: it does not list or download files, and an explicit directory is the upload destination. ii paste provides a copyable root page and a text/plain raw endpoint; --ttl stops it at expiry. ii pac returns a PAC file at its root URL: private, loopback, .local, and plain host names use DIRECT; other destinations use the selected proxy. All five commands accept --port, --bind, and --token [value], print a QR code, LAN URL, and other:, and advertise through ii discover.

LAN Discovery

# List ii send -t, web/dav, and lightweight HTTP services on the same LAN
ii discover

# JSON Lines output
ii discover --json

Discovery waits for three seconds and stays on the local network. It exposes tickets or token URLs to the LAN; it is not access control.

Browser Transfer

ii webrtc

ii webrtc transfers files and text between two browsers. It also supports --port, --bind, and --token. See webrtc.md for limits.

TCP Tunnel

# A: make a service reachable from A available to ticket holders
ii tunnel -s 127.0.0.1:22

# B: use the ticket printed by A
ii tunnel -c ii1k7v...x9a

B listens on 127.0.0.1:8080 by default and increments the port when it is occupied. Use --listen 0.0.0.0:8022 only to expose B's listener to its LAN. Traffic is end-to-end encrypted by Iroh; a ticket holder can use the target until A stops the service. See ii.md for the full protocol and relay options.

SOCKS5 Proxy

ii socks5
ii socks5 --port 1080 --username alice --password secret

ii socks5 is a standalone ordinary network proxy. It listens on a random 0.0.0.0 port by default and prints the actual address. It supports SOCKS5 CONNECT, UDP ASSOCIATE, BIND, IPv4, IPv6, and domain targets. It does not use Iroh, tickets, or relays. For a domain CONNECT, it concurrently tries every address returned by the proxy-side DNS resolver within one 30-second deadline. Supplying --username and --password enables SOCKS5 username/password authentication; both options are required together. To prevent public half-open connections from exhausting resources, it defaults to 100 active connections, a 10-second handshake deadline, and a 5-minute idle CONNECT tunnel timeout. Once either direction closes, the other has at most 5 seconds to finish so half-closed tunnels do not retain resources. When --max is full, new TCP connections remain in the listener backlog until capacity becomes available instead of being immediately closed by the application.

SOCKS5 traffic and RFC 1929 username/password authentication are plaintext. Authentication restricts access but does not encrypt it. A bare public SOCKS5 listener can be scanned or disrupted by the network path; it cannot promise to bypass protocol detection or interference. For encrypted public proxy access, use the existing ii proxy --tls, a VPN, or an SSH tunnel.

Self-hosted Relay

You only need this for a fixed relay endpoint.

# HTTP relay
ii relay --port 8443
ii send .\video.mp4 --relay http://SERVER_PUBLIC_IP:8443

# Temporary self-signed HTTPS relay
ii relay --tls --port 8443
ii send .\video.mp4 --relay https://SERVER_PUBLIC_IP:8443 -k

# Existing PEM certificate
ii relay --tls --domain relay.example.com --port 8443 --cert D:\certs\fullchain.pem --key D:\certs\privkey.pem
ii send .\video.mp4 --relay https://relay.example.com:8443

Without --port, the relay chooses a free port. The terminal prints usable IPv4 URLs; 0.0.0.0 is bind-only, and a cloud public IP may need to come from the provider console. -k is only for self-signed HTTPS. An explicit HTTP or HTTPS relay forces traffic through that relay. Repeating --relay makes ii send probe the explicit relays and select the fastest reachable one; the default n0 relay behavior is unchanged. See ii.md for TLS, NAT, and security boundaries.

Diagnostics

# Inspect the receive path and timing
ii recv ii1k7v...x9a --trace

# Check local networking, ports, permissions, and version
ii doctor
ii doctor --nat
ii version

ii doctor --nat runs a short-lived UDP/NAT/relay probe and reports bound UDP sockets, IPv4/IPv6, NAT mapping behavior, the preferred relay, and relay reachability. Hairpin is explicitly unavailable because Iroh does not expose that probe.

Proxy, Forwarding, and Network Tools

# HTTP/HTTPS forward proxy, with optional Basic authentication
ii proxy --port 8080
ii proxy --username alice --password secret
ii proxy --port 8443 --tls --domain proxy.example.com
ii proxy --port 8443 --tls --cert .\fullchain.pem --key .\privkey.pem

# Forward a local TCP or UDP port to one fixed target
ii tcp db.internal:5432 --port 15432
ii udp game.internal:27015 --port 27015

# TCP connect latency, port checks, and a continuous health check
ii ping api.example.com:443 --count 4
ii port api.example.com 80 443 8443
ii health https://api.example.com/health --interval 10s

# Send a Wake-on-LAN magic packet
ii wake aa:bb:cc:dd:ee:ff --broadcast 192.168.1.255

ii proxy supports HTTP/1.0 and HTTP/1.1 absolute-form requests plus CONNECT. --tls encrypts only the client-to-proxy connection; HTTPS targets remain inside a CONNECT tunnel and are not decrypted. Without --cert and --key, ii generates a temporary self-signed certificate; with both, it loads a PEM certificate chain and private key. --domain sets the certificate DNS name and advertised URL; -k is not supported for ii proxy. ii tcp and ii udp forward to one fixed target; UDP keeps one upstream session per client address and removes idle sessions after five minutes. ii ping measures TCP connect latency rather than sending ICMP. ii port checks TCP ports concurrently. ii health considers only HTTP(S) 2xx/3xx healthy, or checks TCP connectivity for a bare host:port.

Proxy Connectivity Test

ii test https://google.com --socks5 127.0.0.1:10808
ii test https://google.com --http 127.0.0.1:8080
ii test https://google.com --https proxy.example.com:8443

ii test checks the proxy listener, fetches the target URL through the proxy, and measures connection latency. It continues after an individual failure and exits non-zero if any test fails. --https means a TLS-wrapped HTTP proxy and strictly verifies its certificate. Use --username and --password for SOCKS5 or HTTP/HTTPS proxy authentication.

Full Manual

Full command, configuration, and troubleshooting reference: ii.md.

Changelog

CHANGELOG.en.md · CHANGELOG.md

Version

Versions are defined by GitHub Releases and Git tags.

License

MIT License. See LICENSE.