Torm

Torm is a terminal-based BitTorrent client built with TypeScript and Ink. It provides both an interactive terminal user interface (TUI) and a command-line interface (CLI) for managing torrents.

!Torm UI

Features

- Full-screen interactive TUI with keyboard navigation
- Command-line interface for scripting and automation
- Background daemon for persistent downloads
- Support for magnet links and .torrent files
- Drag-and-drop support for adding multiple torrents
- Real-time download/upload speed monitoring
- Peer and tracker information display
- Configurable download paths and settings
- Labels for organizing torrents

Installation

$3

macOS / Linux:

``bash
curl -fsSL https://raw.githubusercontent.com/realAndi/torm/main/scripts/install.sh | bash
`

Windows (PowerShell):

`powershell
irm https://raw.githubusercontent.com/realAndi/torm/main/scripts/install.ps1 | iex
`

Then run torm to launch the TUI.

$3

If you have Node.js or Bun installed:

`bash
npm install -g torm


or


bun install -g torm
`

$3

`bash
git clone https://github.com/realAndi/torm.git
cd torm
bun install
bun run build
`

Usage

$3

Launch the interactive interface by running:

`bash
torm
`

This opens a full-screen terminal interface for managing your torrents.

#### TUI Keyboard Shortcuts

| Key | Action |
|-----|--------|
| q | Quit application |
| ? | Show/hide help overlay |
| Up / k | Select previous torrent |
| Down / j | Select next torrent |
| Enter | Open torrent details |
| Escape | Go back / clear search |
| a | Add new torrent |
| d | Delete selected torrent |
| p | Pause selected torrent |
| r | Resume selected torrent |
| L | Edit labels |
| S | Open settings |
| / | Focus search bar |
| Ctrl+C | Quit (with confirmation) |

#### Detail View

When viewing torrent details, use the number keys to switch tabs:

| Key | Tab |
|-----|-----|
| 1 | General information |
| 2 | Files list |
| 3 | Peers list |
| 4 | Trackers |

$3

Run commands directly without entering the TUI:

`bash
torm [options]
`

#### Available Commands

Adding Torrents

`bash


Add a .torrent file

torm add ubuntu.torrent

Add a magnet link (use quotes)

torm add "magnet:?xt=urn:btih:..."

Add with custom download path

torm add ubuntu.torrent ~/Downloads

Add from clipboard

torm add -c

Add from clipboard with custom path

torm add -c ~/Movies
`

Listing Torrents

`bash


List all torrents

torm list

Aliases

torm ls
`

Torrent Information

`bash


Show detailed torrent info

torm info

Alias

torm show
`

Controlling Torrents

`bash


Pause a torrent

torm pause
torm stop

Resume a torrent

torm resume
torm start

Verify/recheck pieces

torm verify
torm recheck
`

Removing Torrents

`bash


Remove torrent (keeps files)

torm remove

Remove torrent and delete files

torm remove --delete-files

Skip confirmation prompt

torm remove -f
torm remove --force

Aliases

torm rm
torm delete
`

Daemon Management

Torm runs a background daemon to manage downloads:

`bash


Start the daemon

torm daemon start

Check daemon status

torm daemon status

Stop the daemon

torm daemon stop

Restart the daemon

torm daemon restart
`

#### CLI Options

| Option | Description |
|--------|-------------|
| -v, --version | Show version number |
| -h, --help | Show help |
| -c, --clipboard | Read torrent/magnet from clipboard |
| -o, --download-path | Set download path |
| -f, --force | Skip confirmation prompts |
| --delete-files | Delete files when removing torrent |
| --verbose | Show verbose output |

Configuration

Torm stores configuration and data in your home directory:

- Config: ~/.config/torm/ (Linux/macOS)
- Downloads: Default download directory is configurable via settings

Access settings through the TUI by pressing S or configure via the config file.

Architecture

Torm is organized into three layers:

- Engine: Core BitTorrent protocol implementation (tracker communication, peer management, piece selection, disk I/O)
- CLI: Command routing and argument parsing
- UI: Interactive terminal interface built with Ink/React

Known Issues

- Torrents may occasionally need to be deleted twice from the list. This is a known issue being investigated.

Development

`bash


Install dependencies

bun install

Run in development mode

bun run dev

Build

bun run build

Run tests

bun run test

Lint

bun run lint

Format code

bun run format
``

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

Acknowledgments

Torm is built on the shoulders of giants. Thanks to these projects and their maintainers:

$3

- Ink by Vadim Demedes - React for CLIs, the foundation of Torm's terminal UI
- React by Meta - The declarative UI paradigm that makes the TUI possible
- meow by Sindre Sorhus - CLI argument parsing done right
- geoip-lite - IP geolocation for peer country flags
- ink-scroll-list - Scrollable lists for Ink

$3

- Bun by Oven - The fast JavaScript runtime that powers Torm
- TypeScript by Microsoft - Type safety for the entire codebase
- Vitest - Fast unit testing framework

$3

Torm implements the BitTorrent protocol from scratch, guided by:

- BEP 3 - The BitTorrent Protocol Specification
- BEP 9 - Extension for Peers to Send Metadata Files
- BEP 10 - Extension Protocol
- BEP 11 - Peer Exchange (PEX)
- BEP 15 - UDP Tracker Protocol

License

Torm is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This ensures the project remains open source and improvements stay accessible to the community.

Disclaimer

Torm is a BitTorrent client implementing an open protocol. Users are responsible for complying with applicable laws and regulations in their jurisdiction.