tork

/\_/\
( ^.^ )  a cozy terminal for torrent search + verified downloads
 > ^ <

You name it, the cat fetches it. Search public torrent indexes, compare the actual swarm, and keep downloads in one calm little terminal app.

!tork home screen

What it does

• Search Knaben, YTS, Nyaa, plus your own RSS or Torznab feeds.
• Fold the same torrent listed on several indexes into a single row, and grab it

• Group duplicate releases, rank the useful ones, and surface seeders, size,

• Preview a magnet, queue it with one key, then pause, verify, seed, move, or

• Browse and grab current official Linux ISOs from Ubuntu, Debian, Fedora,

• Run tork doctor when a provider or local setup feels off, and use the swarm

!tork search results

Install

brew tap melqtx/tap && brew install tork             # macOS (Homebrew)
yay -S tork                                          # Arch (AUR)
nix run github:melqtx/tork                           # Nix
go install github.com/melqtx/tork/cmd/tork@latest    # Go 1.26+

If Go on macOS is picking Nix's compiler, use Apple Clang for the install:

CC=/usr/bin/clang CXX=/usr/bin/clang++ go install github.com/melqtx/tork/cmd/tork@latest

Build from source

Building tork requires Go 1.26 or newer. From the repository root, run it directly without creating a binary:

go run ./cmd/tork

Or build and run a local binary:

go build -o ./bin/tork ./cmd/tork
./bin/tork

Config lives in ~/.tork/; downloads land in ~/Downloads/tork (change with tork -d DIR).

Already have a torrent? Paste its magnet link, bare infohash, local .torrent path, or .torrent URL into the same home search box. To go straight to the quiet file preview:

tork 'magnet:?xt=urn:btih:…'
tork ~/Downloads/linux.iso.torrent
tork 'https://example.org/linux.iso.torrent'
tork --torrent-url 'https://example.org/download?id=123'

Nothing starts downloading until you confirm it. enter takes whatever is selected, from wherever the cursor happens to be. Tracker adverts, NFO and checksum files, and sample clips start deselected in a collapsed Extras group — the header says how many were grouped, and a puts them back. Expand the group with → to inspect them, or select the entire group with Space. The preview shows selected size, the save folder, and the Enter-to-download action together above the file list. If a bare hash is still finding metadata peers, wait to choose individual files or press enter to queue the whole torrent immediately. Once metadata arrives, tork keeps a private bounded copy under ~/.tork/metainfo/, so reopening or resuming that magnet no longer depends on finding a metadata peer.

Cache defaults are conservative and can be changed in ~/.tork/config.yaml:

metadata_cache:
  enabled: true
  max_mb: 256
  max_entries: 512

Advanced torrent-client limits are optional; zero or omitted values retain the anacrolix defaults:

torrent_tuning:
  half_open_conns_per_torrent: 25
  total_half_open_conns: 100
  piece_hashers_per_torrent: 2
  max_unverified_bytes: 67108864
  dial_rate_limit: 10
  peer_high_water: 500
  peer_low_water: 50
  download_rate_limit: 0
  upload_rate_limit: 0
  disable_aggressive_upload: false
  no_upload: false

Transfer rates are client-wide bytes per second; dial rate is dials per second. no_upload prevents all torrent uploads, including seeding. The torrent library does not expose its webseed concurrency as a runtime client setting, so tork does not claim to configure it here.

Direct HTTP downloads use verified byte ranges when the server supports them:

direct:
  max_connections: 4
  min_chunk_size: "10MB"
  enable_chunking: true

The connection limit is per direct download. tork confirms range support and a stable resource before splitting; small, unknown-length, or incompatible responses automatically use one sequential connection. Paused segmented transfers resume from an internal .part.meta sidecar, and the final filename still appears only after its published SHA-1, SHA-256, or SHA-512 digest is verified.

SOCKS5 proxy

For the usual local Tor setup, one command is enough:

tork proxy tor
tork doctor --proxy-check

tork proxy status shows the redacted endpoint and strict-mode limits without making a network request. To use another unauthenticated SOCKS5 proxy:

tork proxy set socks5://127.0.0.1:1080

For an authenticated endpoint, run tork proxy set without an argument and enter the URL through hidden terminal input, so it never appears in shell history or a process list. You can also configure tork by hand:

proxy:
  socks5: "socks5://user:[email protected]:9050"

socks5:// and socks5h:// both resolve destination names at the proxy. Username and password are optional and must be URL-encoded. For Tor, the usual local endpoint is socks5://127.0.0.1:9050.

Credentials require ~/.tork/config.yaml to be a regular file with mode 0600. A normal tork launch tightens an insecure regular config once; tork doctor stays read-only and reports the problem instead.

Proxy mode is strict: searches, ISO requests, HTTP trackers, and outgoing TCP peers use the proxy. tork disables DHT, uTP, UDP trackers, inbound peers, port forwarding, and WebTorrent rather than risk a direct connection. Downloads may find fewer peers as a result. The TUI keeps a visible SOCKS strict badge; it becomes ((o)) Tor strict only after a live verification confirms a Tor exit. A check-service outage is shown as unavailable, not as a leak, and tork never falls back to a direct connection.

Keep an eye on it

tork doctor is read-only by default and checks config, disk, state, cached metadata, and provider reachability. Add --engine for an opt-in listener check, --record to save provider results in ~/.tork/health.json, or --proxy-check to ask the Tor Project's check service what egress IP it sees through your configured proxy. That proves this explicit HTTP check used the route; it is not a promise of anonymity or a claim about your normal connection. Health history contains local provider timings plus torrent names and swarm counts; it is never uploaded.

Automatic checks are off by default. Enable a local daily check with:

health:
  enabled: true
  interval_hours: 24

The check sends the generic 1080p canary query to enabled providers. Press H in tork to view saved source and swarm history, or r there to record a manual check.

Keys

Press ? anywhere for the full list of keys on the current screen. The highlights:

• home type to search, ↓ focus the destination menu, ↑↓ move, enter activate the focused control; esc returns to the search field, then clears it
• isos ↑↓ browse, enter grab the latest official image
• results enter preview (or download when preview is disabled), D grab now, Y copy magnet, / filters, v top picks / full list, f advanced text filter
• preview enter download what's selected, space toggle a file or folder, ←→ fold, a/n select all or none
• downloads enter open the file, o show it in your file manager, p pause/resume, s seed, v fully verify completed data, m move, r relink, y copy full path, Y copy magnet, x remove, d delete data
• On home, tab / shift+tab moves between the search field and menu choices.
• From results or Linux ISOs, tab opens downloads; tab or esc returns to where you were. ^d also opens downloads.
• esc goes back or cancels the current dialog; ^c quits
• Preview, move/relink, and removal dialogs keep focus until finished or cancelled.
• The ? help panel scrolls with ↑↓ or pgup/pgdn on smaller terminals.

A result tagged yts+2 is one torrent that three indexes listed. Rather than spend three lines on it, tork keeps the fullest release name, the best swarm numbers any of them reported, and — the part that matters once the download starts — the combined tracker list, so it announces to every swarm all three knew about instead of the slice one listing happened to carry. The status line counts how many listings were folded away; press v and the detail panel names the sources and the tracker total. Results that only link to a details page keep their own row: without a magnet there is no infohash to compare, and tork will not fetch every page just to find out.

Search results start with up to three picks per resolution. Use arrows to choose one and Enter to preview it. Each group has a "Show more" row when more releases are available. Unknown resolutions remain under "Other / unspecified".

Press / for a filter panel: choose multiple resolutions with Space, set a maximum size, and choose Balanced, Smaller files, or Higher quality. Enter applies; Escape cancels. No checked resolutions means all. Choices persist across searches in the current session. Size limits exclude unknown sizes. Title, year and episode matches rank before reported swarm counts; these counts do not guarantee speed. A selected release stays visible while new results stream in. Result rows use shorter readable titles, with source/codec, size and reported seed counts alongside them on wider terminals. The original release filename stays in the details.

Press v for the full filtered list. Advanced text filters still compose with these choices. Press f and try:

res:1080p,2160p seeders:>20 size:<8gb
linux codec:x265 -source:cam
provider:nyaa category:anime is:trusted
is:hdr -is:dv

Available fields are res, seeders, size, source, codec, provider, and category. Attributes include is:trusted, is:hdr, is:dv, and is:pack; prefix any structured filter with - to negate it.

Verification rehashes completed torrent pieces and direct-download checksums. Checksum mismatches are moved aside as .corrupt, .corrupt.1, and so on before retrying.

Autopilot (WIP)

Describe what you want and let the cat make a plan:

tork autopilot "all breaking bad seasons 1080p under 40GB"
tork autopilot --dry-run --min-seeders 20 "dune 2024 2160p"

Autopilot shows its picks, total known size, reasons, and a summary of rejected results before asking to queue anything. Use -n N to cap the picks, --max-size 8GB to cap each download, or --category movies,anime to narrow provider categories. When the same limit appears in several places, the flag wins over the request text, which wins over config defaults. --headless skips the TUI but still asks before queuing; scripts and cron jobs need --yes. Decisions stay local in ~/.tork/autopilot.jsonl so a strange choice can be inspected later.

Persistent defaults can live under autopilot in ~/.tork/config.yaml:

autopilot:
  max_downloads: 3
  min_seeders: 10
  max_size_gb: 40
  allowed_categories: [movies, anime]

Legal

tork is a BitTorrent client and search tool. It does not host files, operate trackers, or control the third-party providers it can search.

Use it only for content you are allowed to download and share, such as official Linux ISOs, public-domain media, open-source software, and your own files. You are responsible for following local law and the terms of any provider you enable.

Provider availability and results can change without notice. tork does not endorse or guarantee third-party content.

A proxy routes tork's traffic, but it is not a promise of anonymity or legal protection.

MIT, see LICENSE.