← Back to home
CLI reference
Complete command-line reference for fast-copy — every flag, subcommand and endpoint form. Invoke it as python fast_copy.py or, from a packaged build, as fast-copy. Looking for copy-paste walkthroughs instead? Start with the guides.
CLI Syntax
python fast_copy.py [options] source [source ...] destination
When two or more positionals are given, the last is the destination and earlier ones are sources (cp -r style). Each source can be a local path, a glob pattern, or a remote SSH path in the form user@host:/path.
All Options
Positional arguments
| Argument | Description |
|---|---|
| source | One or more source folders, files, globs, or remote user@host:/path |
| destination | Destination path or remote user@host:/path |
General options
| Flag | Default | Description |
|---|---|---|
| --buffer BUFFER | 64 | Buffer size in MB. 8 for low-memory systems, 128 for fast SSDs. |
| --threads THREADS | 4 | Threads used for hashing and physical layout resolution. |
| --dry-run | — | Show the copy plan without writing any data. |
| --no-verify | — | Skip post-copy hash verification. |
| --no-dedup | — | Disable deduplication. Faster for known-unique files. |
| --hash ALGO | auto | Hash algorithm: auto (xxh128 if installed, else sha256), xxh128, sha256. |
| --no-cache | — | Disable the persistent SQLite hash cache. |
| --force | — | Skip pre-flight space check. |
| --overwrite | — | Overwrite all files, skipping identical-file detection. |
| --exclude EXCLUDE | — | Exclude files/dirs by name or glob (repeatable). |
| -R, --keep-parents | — | Preserve each source's full parent path under the destination (rsync -R semantics, v3.1.2+). Multi-source and glob copies only — single-source copies emit a one-line note and are unchanged. fast-copy -R /etc /var/log dst/ produces dst/etc/ and dst/var/log/ instead of dst/etc/ and dst/log/. Use for incident snapshots and forensic captures where source provenance must be preserved. |
| --use-sudo | — | Re-exec self under sudo if not already root (v3.1.0+, hardened in v3.1.1+). Refuses to elevate if the script or its directory is group/world-writable. Linux/macOS only. |
| --update [VERSION] | — | Download and install latest (or a specific version). Refused under sudo (v3.1.1+). Supports --update-sha256 <hex> for out-of-band integrity pinning (v3.1.1+). |
SSH source options
| Flag | Description |
|---|---|
| --ssh-src-port PORT | SSH port for the remote source (default: 22) |
| --ssh-src-key PATH | Path to SSH private key for the remote source |
| --ssh-src-password | Prompt for SSH password for the remote source |
SSH destination options
| Flag | Description |
|---|---|
| --ssh-dst-port PORT | SSH port for the remote destination (default: 22) |
| --ssh-dst-key PATH | Path to SSH private key for the remote destination |
| --ssh-dst-password | Prompt for SSH password for the remote destination |
General SSH options
| Flag | Description |
|---|---|
| -z, --compress | Enable SSH compression. Recommended for slow or high-latency links. |
Utility Commands
Check optional dependencies
fast-copy deps fast-copy deps --install
Reports which optional packages are installed (cloud SDKs, faster hashing, SSH). Aliases: deps, check-deps, doctor.
Version & updates
fast-copy --version fast-copy --check-update fast-copy --update [VERSION]
Guides & Examples
Worked, copy-paste examples for each transfer type moved to task-focused guides:
- Local copies — USB drives, globs, single files, multi-source, Windows.
- SSH transfers — tar-pipe push / pull / relay, custom ports & keys, Synology.
- Cloud storage — S3 / Azure / GCS endpoints and the creds manager.
- Sparse files & VM images — SEEK_DATA/SEEK_HOLE extent walking, Longhorn & libvirt.
- Sudo backups — system paths with self-elevation and the audit log.
- Everyday options — dry runs, excludes, buffers, dedup toggles.