| name | filetransfer |
| description | Download files from URLs — and whole Hugging Face repos/models — using aria2: resumable, multi-connection (fast on big files), concurrent, with a live progress window (AriaNg in the browser). Use this INSTEAD OF `curl -O` / `wget` / `huggingface-cli download` / `hf download` whenever the goal is to SAVE A FILE to disk — a release asset, tarball/zip, dataset, model weights, ISO, image, audio, or video, and especially anything large or slow. For Hugging Face use `filetransfer hf <repo>`: it fetches the whole repo by default, handles Xet-backed files, is idempotent (skips complete, resumes partial, refreshes expired signed URLs), self-heals errored transfers, and auto-verifies sha256 on completion. Big downloads auto-open a progress window; the download keeps running after the command returns, after the window is closed, and after the session ends. Do NOT use it for fetching API JSON/HTML to stdout or a pipe — keep using curl for that. |
filetransfer
A Claude-driven downloader that wraps aria2 and shows progress in AriaNg (opened in the browser). When you need to save a file to disk, reach for filetransfer download instead of curl -O / wget.
When to use
- Downloading any file to disk: release assets, tarballs/zips, datasets, model weights, ISOs, images, audio, video.
- Downloading a Hugging Face repo/model/dataset — prefer
filetransfer hf over huggingface-cli/hf download.
- Especially large or slow downloads — you get multi-connection speedup, automatic resume on failure, and a live progress bar.
When NOT to use
- Fetching an API response, JSON, or HTML to stdout or into a pipe → keep using
curl.
Commands
filetransfer download <url>... [--dir DIR] [--out NAME] [--window] [--no-window]
filetransfer hf <repo> [--include GLOB]... [--exclude GLOB]... [--revision REV] [--repo-type model|dataset|space] [--link DIR]
filetransfer verify <repo> [--include GLOB]... [--fix]
filetransfer list # all transfers, as a table
filetransfer status [gid] # one transfer (or all)
filetransfer window # open the progress window on demand
filetransfer pause <gid>
filetransfer resume <gid>
filetransfer cancel <gid>
filetransfer daemon start|stop|status
- Destination:
download defaults to the current directory (--dir to change). hf/verify always use the canonical store ~/.filetransfer/models/<repo> (override with FT_MODELS_DIR), independent of cwd — a repo can't be downloaded to two places. Use --link DIR to symlink a project path to the store copy.
- Big files (>50 MB or unknown size) auto-open the AriaNg progress window. Small files stay quiet and just print a progress URL. Force with
--window, suppress with --no-window.
- The Engine (
aria2c --enable-rpc) starts automatically on the first download and stays resident, so transfers keep running after the command returns, after the window closes, and after the session ends. Stop it with filetransfer daemon stop.
Hugging Face
filetransfer hf <repo> downloads the whole repo by default (configs included; use --include/--exclude globs to narrow). Every repo goes to one canonical path ~/.filetransfer/models/<repo> regardless of cwd, so it is never downloaded twice; --link DIR symlinks a project path to that single copy. Xet-backed files download over the HTTPS xet bridge — no special handling. Re-running is idempotent: complete files are skipped, in-flight/partial ones are refreshed with a fresh signed URL and resumed. Errored transfers self-heal (the manager re-adds them with a fresh URL), and once a repo finishes it is auto-verified (size + sha256) and any corrupt file is re-downloaded. Run filetransfer verify <repo> --dir ... [--fix] to check/repair on demand. Set HF_TOKEN for gated repos, HF_ENDPOINT for a mirror.
Install
Requires aria2:
brew install aria2
go install github.com/sunfmin/filetransfer@latest
