# webtorrent-cli: Command-Line BitTorrent Downloads and Playback

> webtorrent-cli packages WebTorrent for Node.js command-line use, with downloads, on-demand streaming, peer discovery, seeding, and torrent metadata tools. It suits users who want terminal control, although playback depends on external players and receivers.

**webtorrent/webtorrent-cli** — WebTorrent, the streaming torrent client. For the command line.

- Repository: https://github.com/webtorrent/webtorrent-cli
- Website: https://webtorrent.io
- Stars: 1,384 · Forks: 152
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/webtorrent-webtorrent-cli

## Why webtorrent-cli Fits a Terminal Workflow

webtorrent-cli addresses a specific gap between browser-oriented WebTorrent and command-line download workflows. The project description calls it a streaming torrent client for the command line, while the package metadata identifies Node.js as its runtime. It is intended for people who download or seed torrents from a terminal, pass player arguments through a shell, inspect metadata, or automate repeatable torrent operations without moving to a graphical interface.

The package handles more than basic file transfer. Its documented commands can download a torrent, retrieve metadata without immediately selecting content, seed a file or directory, create a `.torrent` file, inspect torrent information, and print version or help information. Inputs may be magnet URIs, HTTP URLs for `.torrent` files, filesystem paths, or hexadecimal info hashes. That range makes the client useful for local material as well as remote torrent sources.

This is not the browser WebTorrent package. The README directs browser users to the separate `webtorrent` npm package and identifies `webtorrent-cli` specifically as the command-line application. Its distinguishing feature is control through flags and commands while retaining streaming playback and peer-facing torrent behavior.

## Torrent Acquisition and Playback Data Flow

The CLI accepts a torrent identifier, parses the requested content, and uses the `webtorrent` dependency for torrent operations. The package also depends on `parse-torrent`, while `create-torrent` supports the `create` command. Network discovery is distributed across components named in the documentation: `bittorrent-dht`, `bittorrent-tracker`, `ut_metadata`, and `ut_pex`. These cover tracker announcements, peer discovery, magnet metadata exchange, and peer exchange.

For streaming, the README says pieces are fetched from the network on demand. That mechanism explains why playback and seeking can begin before the complete torrent has been downloaded. The client selects a media file, exposes or hands its data to a supported player or device, and fetches the pieces required for the requested position. The documented player targets include AirPlay, Chromecast, VLC, IINA, MPlayer, MPV, OMX, DLNA, SMPlayer, and XBMC.

The download path is more conventional. By default, downloads go to the current directory, while streaming uses a temporary folder. The `-o` or `--out` option changes the download destination. A completed download can stop by default, while `--keep-seeding` keeps the client running after the download finishes. The README also documents `--no-quit`, which prevents the client from quitting when the player exits.

## Installing webtorrent-cli and Checking Its Command Surface

The documented installation is a global npm install. The package metadata requires Node.js `>=20`, so the runtime should be checked before installation. After npm finishes, `webtorrent --help` prints the command list, accepted torrent identifiers, streaming targets, and available options.

```bash
npm install webtorrent-cli -g
```

This command installs the package globally and exposes the executable declared as `webtorrent` in `package.json`. The next command confirms that the executable can start and displays its help interface:

```bash
webtorrent --help
```

The help output should include commands such as `download`, `downloadmeta`, `seed`, `create`, `info`, `version`, and `help`. It also documents default paths and flags for HTTP and torrent ports. No browser-based graphical setup is required by this package.

Because the package is published under the MIT license, the repository grants use under that license's terms. That is a project-level licensing statement, not an assessment of rights in every torrent, media file, protocol extension, or external player involved in a particular use.

## First Download and File Selection

A cautious first use begins with the documented `info` command. The general usage syntax identifies the command as `webtorrent info <torrent-id>`, where the identifier may be a magnet URI, HTTP URL, filesystem path, or hexadecimal info hash.

```bash
webtorrent info <torrent-id>
```

The README says this command shows torrent information. It does not define a particular output format or guarantee that every remote source will be reachable, so the command can still be affected by an unavailable source or a malformed torrent.

Downloading is the default command, but it can also be stated explicitly. The README provides this example:

```bash
webtorrent download "magnet:..." --vlc
```

This example begins a download and selects VLC for streaming. Without `--out`, the README states that a download goes to the current directory. A torrent containing multiple files introduces a selection step. The default behavior lists files, `--select` accepts a specific file, and `--interactive-select` provides an interactive selection interface. A torrent containing one file is not documented as requiring selection.

For an explicit destination, use `-o` or `--out`. The README does not document automatic conflict handling, overwrite policy, or completed-file verification, so those behaviors should not be assumed.

## Streaming to VLC With Player Control

Streaming adds an external dependency: a supported player or receiver must be available and configured. The README uses VLC as its concrete player example and documents player-specific arguments through `--player-args`.

```bash
webtorrent download "magnet:..." --vlc
```

The magnet URI is an illustrative placeholder in the README, not a complete public torrent identifier. A reader should replace it with a valid magnet URI or use one of the accepted local or remote `.torrent` inputs.

Player behavior can be adjusted with the documented command:

```bash
webtorrent "magnet:..." --vlc --player-args="--video-on-top --repeat"
```

Here, `--vlc` selects the player, while the quoted `--player-args` value is passed using the arguments shown in the README. Other switches include `--playlist`, `--pip`, and `--not-on-top`. The README explicitly notes that Picture-in-Picture is entered if the player supports it, which is a direct limitation of the feature.

The HTTP server port defaults to `8000` and can be changed with `-p` or `--port`. Torrent and DHT ports default to random values and have separate options. These settings matter on networks where the client must use specific ports. The README does not promise automatic router configuration or UPnP behavior, so port-forwarding requirements are not established.

## Operational Limits, Network Settings, and Browser Alternative

webtorrent-cli is the wrong choice when WebTorrent must run inside a browser. The README sends browser use to the separate `webtorrent` npm package. That package uses the browser platform directly, while `webtorrent-cli` invokes `webtorrent` from Node.js and exposes shell commands and options. This is a real architectural difference, not merely a naming preference.

The CLI also depends on peers, trackers, DHT, reachable ports, and media-player integration. Magnet support depends on the documented `ut_metadata` extension. Peer discovery depends on DHT, trackers, and `ut_pex`. Failure to reach peers or blocked outbound traffic can prevent useful transfer rates, although the README does not define retries or recovery behavior.

Operational controls include speed limits, blocklists, custom tracker announcements, quiet mode, and protocol details. Each corresponds to a documented flag:

```bash
webtorrent download "magnet:..." --vlc
```

The command illustrates the streaming path, while the help output separately documents `--download-limit` and `--upload-limit` in kb/s. It also documents `-b` for a blocklist file or URL and `-a` for a tracker URL. These settings let an operator constrain a session, but they also increase the amount of configuration that must be understood.

The repository is not archived, and its last push was on 2026-10-15. Recent releases include `v6.0.1` on 2026-08-19 and `v6.0.0` on 2026-04-14. Maintenance status is not a measure of every downstream dependency or external receiver. Upgrade cost is at least partially bounded by the documented Node.js `>=20` requirement and the package's release line. The README does not document a migration guide for each major release, rollback procedure, or compatibility policy for individual players.

## Conclusion

Choose webtorrent-cli when Node.js is already available and terminal control over BitTorrent downloads or supported player targets matters. Do not choose it when browser-native WebTorrent is required or guaranteed access to an external media player is essential. Before adoption, verify Node.js 20 or later, the torrent source, required peer ports, and the selected player integration. For a scripted first check, run `webtorrent info <torrent-id>` before starting a download or player session.

## FAQ

### How do I install webtorrent-cli?

Run `npm install webtorrent-cli -g`. The package metadata requires Node.js 20 or later, and the installation exposes the `webtorrent` executable.

### What torrent inputs does webtorrent-cli accept?

It accepts magnet URIs, HTTP URLs for `.torrent` files, filesystem paths to `.torrent` files, and hexadecimal info hashes. The available commands also include downloading metadata and showing torrent information.

### Can webtorrent-cli stream before a torrent finishes downloading?

The README states that pieces are fetched on demand, allowing streaming and seeking before the torrent is complete. Playback still depends on a supported external player or receiver.

### Which license does webtorrent-cli use?

The README metadata and `package.json` identify the project license as MIT. That statement applies to the project package, not to separately distributed media or torrent content.

### Does webtorrent-cli run in the browser?

No. The repository describes `webtorrent-cli` as a Node.js command-line application and directs browser users to the separate `webtorrent` npm package.

## Sources

- [License: MIT](https://github.com/webtorrent/webtorrent-cli/blob/master/LICENSE)
- [Project website](https://webtorrent.io)
- [README](https://github.com/webtorrent/webtorrent-cli/blob/master/README.md)
- [Releases](https://github.com/webtorrent/webtorrent-cli/releases)
- [webtorrent/webtorrent-cli on GitHub](https://github.com/webtorrent/webtorrent-cli)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/webtorrent-webtorrent-cli