fetchtv

A Node.js CLI tool to download Fetch TV PVR recordings over the local network.

No Fetch credentials or cloud account required.

Based on lingfish/fetchtv-cli (Python) which is based on jinxo13/FetchTV-Helpers (also Python).

Contents

• Demo
• Quick Start
• Installation
• Usage
• Template Variables
• Examples
• Programmatic API
• Tests
• GitHub Workflows
• Disclaimer
• Support

Demo

https://gist.github.com/user-attachments/assets/61dfab62-a715-4cc3-a4d1-93ee0db43827

Quick Start

• Install fetchtv
• Run fetchtv

Installation

• NPX (Easiest)
• Node.js from Source
• Docker from Source

Installation: NPX

The easiest way to install fetchtv is via NPX.

First, ensure Node.js is running:

node --version # Ideally >= v22.x but fetchtv is >= v18.x compatible

Then, run fetchtv via NPX:

npx fetchtv             # Run the tool
npx fetchtv@latest      # (optional) "@latest" ensures package is up-to-date
npx -y fetchtv@latest   # (optional) "-y" flag skips any prompts

npx fetchtv info
npx fetchtv shows
npx fetchtv recordings

# etc…

If you encounter permissions errors with npx try running npx clear-npx-cache prior to running npx -y fetchtv (this clears the cache and re-downloads the package).

Installation: Node.js from Source

1. Clone the fetchtv repository:
   

   git clone https://github.com/furey/fetchtv.git
   

2. Navigate to the cloned repository directory:
   

   cd /path/to/fetchtv
   

3. Ensure Node.js is running:
   

   node --version # Ideally >= v22.x but fetchtv is >= v18.x compatible
   

4. Install Node.js dependencies:
   

   npm ci
   

5. Run fetchtv:
   

   node fetchtv.js
   node fetchtv.js info
   node fetchtv.js recordings
   node fetchtv.js shows
   
   # etc…
   

Optional: Link fetchtv Tool

You may optionally link the fetchtv tool to your system path for easier access:

npm link

This will create a symlink to the fetchtv command in your global node_modules directory, allowing you to run it from anywhere in your terminal:

fetchtv
fetchtv info
fetchtv shows
fetchtv recordings

# etc…

To uninstall the linked tool, run:

npm unlink

Installation: Docker from Docker Hub

Pre-built multi-arch (linux/amd64, linux/arm64) images live at furey/fetchtv — no clone or build required:

docker run --rm --network host furey/fetchtv info
docker run --rm --network host furey/fetchtv recordings

See the Docker Hub overview for a focused quick-start.

Installation: Docker from Source

1. Clone the fetchtv repository:
   

   git clone https://github.com/furey/fetchtv.git
   

2. Navigate to the cloned repository directory:
   

   cd /path/to/fetchtv
   

3. Ensure Docker is running:
   

   docker --version # Ideally >= v27.x
   

4. Build the Docker image:
   

   docker build -t fetchtv .
   

5. Run the container:
   

   docker run -t --rm fetchtv
   docker run -t --rm fetchtv info
   docker run -t --rm fetchtv shows
   docker run -t --rm fetchtv recordings
   
   # etc…
   

UPnP/SSDP Discovery Issues

UPnP/SSDP discovery can be unreliable in Docker containers.

To work around this, it's recommended to specify your Fetch TV server's IP address directly with the --ip (and optionally --port) option when running the container. For example:

docker run -t --rm fetchtv
docker run -t --rm fetchtv info --ip=192.168.86.71
docker run -t --rm fetchtv shows --ip=192.168.86.71
docker run -t --rm fetchtv recordings --ip=192.168.86.71

# etc…

Usage

If you installed via NPX, you can run it from anywhere:

npx fetchtv <COMMAND> [OPTIONS]

If you installed from Node.js source, you can run it from the cloned repo directory:

cd /path/to/fetchtv
node fetchtv.js <COMMAND> [OPTIONS]

If you linked the tool after installing from source, you can run it from anywhere:

fetchtv <COMMAND> [OPTIONS]

Template Variables

fetchtv recordings --save=./downloads --template='${show_title}/${recording_title}.${ext}'

When using --template, the following variables are available:

Plex-Compatible Template

The --for-plex option uses a predefined template optimized for Plex media server:

`${show_title}/Season ${season_number}/${show_title} - S${season_number}E${episode_number_padded}.${ext}`

Example Templates

Save recordings with show folder:

${show_title}/${recording_title}.${ext}

Save recordings with show folder and SXXEXX episode naming:

${show_title}/S${season_number_padded}E${episode_number_padded}.${ext}

Save recordings with show and season folders:

${show_title}/Season ${season_number}/${recording_title}.${ext}

Examples

Search for Fetch TV servers:

fetchtv

Display Fetch box details (uses auto-discovery):

fetchtv info

List recorded show titles:

fetchtv shows --ip=192.168.86.71

List recordings:

fetchtv recordings --ip=192.168.86.71

List recordings and output as JSON:

fetchtv recordings --ip=192.168.86.71 --json

Save new recordings to ./downloads (creates directory if needed):

fetchtv recordings --ip=192.168.86.71 --save=./downloads

Save new recordings but exclude show titles containing News:

fetchtv recordings --ip=192.168.86.71 --exclude=News --save=./downloads

Save new episodes for the show MasterChef:

fetchtv recordings --ip=192.168.86.71 --show=MasterChef --save=./downloads

Save & overwrite specific MasterChef episodes containing S04E12 or S04E13:

fetchtv recordings --ip=192.168.86.71 --show=MasterChef --title=S04E12 --title=S04E13 --save=./downloads --overwrite

List only items currently being recorded:

fetchtv recordings --ip=192.168.86.71 --is-recording

Save only items currently being recorded:

fetchtv recordings --ip=192.168.86.71 --is-recording --save=./in-progress

Save recordings using a custom path template:

fetchtv recordings --ip=192.168.86.71 --save=./downloads --template='${show_title}/${recording_title}.${ext}'

Save recordings in Plex-compatible path format:

fetchtv recordings --ip=192.168.86.71 --save=./media --for-plex

Programmatic API

In addition to the CLI, fetchtv.js can be imported as an ES module by other Node projects that want to drive a Fetch TV box programmatically (e.g. a long-running watcher that mirrors new recordings into a media library).

import {
  discoverFetchServers,
  discoverFetch,
  getFetchRecordings,
  downloadFile
} from 'fetchtv'

// Enumerate every Fetch TV box on the LAN
const servers = await discoverFetchServers()

// Or grab a single box by IP (returns the full UPnP location object
// needed by the other helpers below)
const location = await discoverFetch({ ip: '192.168.1.50', port: 49152 })

// List recordings (optionally filtered)
const shows = await getFetchRecordings({
  location,
  filters: {
    folderFilter: [],       // include only shows whose title contains any of these (lowercased)
    excludeFilter: [],      // exclude shows whose title contains any of these (lowercased)
    titleFilter: [],        // include only items whose title contains any of these (lowercased)
    showsOnly: false,       // true → return just the show folders, no items
    isRecordingFilter: false // true → return only items still being recorded
  }
})

// Download a single item
await downloadFile({
  item: shows[0].items[0],
  filePath: '/tmp/example.ts',
  progressBar: null,
  overwrite: false
})

isCurrentlyRecording / downloadFile recognise two distinct "still recording" sentinels in the UPnP directory listing: the 4398046510080-byte marker, and any non-positive size (typically -1, used by Fetch TV when a recording has started but its final size isn't known yet). Both cause downloadFile to refuse the download — partial bytes from an in-progress recording would otherwise be written out as a truncated file.

Deletion is intentionally not exposed: Fetch TV firmware advertises the standard UPnP DestroyObject action in its ContentDirectory SCPD but its request handler rejects it (Unknown Service Action), and HTTP DELETE on the item URL returns 501. The Fetch box's real control plane for deletion lives in Fetch's cloud APIs (auth + WebSocket to messages.fetchtv.com.au) and is out of scope for this LAN-only library.

The module is safe to import — running the CLI requires invoking fetchtv.js directly as a script.

Tests

A feature-level test suite covers every command and code path that doesn't require talking to a real Fetch TV box:

npm install
npm test

Tests use Node's built-in node:test runner (no external framework) and nock to intercept HTTP. The CLI-level tests in test/commands.test.js stand up a local http.createServer and spawn node fetchtv.js --ip 127.0.0.1 --port <random> against it.

Tests run locally only — there's no CI gate.

GitHub Workflows

Three workflows automate publication and presentation. Two run on release; one keeps the Docker Hub overview in sync.

Publish to NPM

Checks out the repo, sets up Node.js 22, runs npm ci, then npm publish against the public NPM registry using the NPM_TOKEN secret.

Publish to Docker Hub

Builds multi-arch images (linux/amd64, linux/arm64) via Buildx + QEMU, authenticates with DOCKERHUB_USERNAME / DOCKERHUB_TOKEN, and pushes tags derived from the release's semver ({{version}}, {{major}}.{{minor}}, latest) to furey/fetchtv.

Sync Docker Hub Description

Pushes DOCKER_README.md to the furey/fetchtv Docker Hub overview using peter-evans/dockerhub-description@v4. Uses the same DOCKERHUB_USERNAME / DOCKERHUB_TOKEN credentials as the image-publish workflow. Triggers on any push to main that touches the README or the workflow file, and can be run manually via workflow_dispatch.

Disclaimer

This project:

• Is licensed under the GNU GPLv3 License.
• Is not affiliated with or endorsed by Fetch TV.
• Is a derivative work based on lingfish/fetchtv-cli.
• Is written with the assistance of AI and may contain errors.
• Is intended for educational and experimental purposes only.
• Is provided as-is with no warranty—please use at your own risk.

Support

If you've found this project helpful consider supporting my work through:

Buy Me a Coffee | GitHub Sponsorship

Contributions help me continue developing and improving this tool, allowing me to dedicate more time to add new features and ensuring it remains a valuable resource for the community.