# Filetransfer

> 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.

- Skill: `sunfmin/filetransfer` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add sunfmin/filetransfer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sunfmin/filetransfer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: sunfmin (https://skillmd.com/u/sunfmin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sunfmin/filetransfer

---


# 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
```