TidyFlix

Current version: 1.2.1 (released 2026-04-05)

A terminal UI for renaming messy TV show and movie filenames into clean, configurable formats.

star.trek.discovery.s02e04.1080p.bluray.mkv
→ Star Trek Discovery - S02E04.mkv

the.matrix.1999.bluray.remux.2160p.mkv
→ The Matrix (1999).mkv

Requirements

• Node.js 18+ — nodejs.org/en/download

Installation

npm install -g tidyflix

Starting the app

tidyflix

This opens the main menu with four options: Rename a file, Batch rename a folder, Settings, and Quit. Use the arrow keys to navigate and Enter to select.

To check the installed version without opening the TUI:

tidyflix --version

CLI shortcut — rename a single file directly

tidyflix rename /path/to/file.mkv

This skips the home screen and opens the rename screen with the file path pre-filled.

Renaming a single file

1. Select Rename a file from the home menu (or use the CLI shortcut above).
2. Enter the full path to the file. Press Enter to confirm.
3. TidyFlix parses the filename and shows a preview of the new name.
4. Confirm the rename with Enter, or go back to cancel.

Both video and subtitle files are supported (e.g. .mkv, .mp4, .srt).

Batch renaming a folder

1. Select Batch rename a folder from the home menu.
2. Enter the path to the folder. Tab completion is available — press Tab to cycle through matching directories.
3. TidyFlix scans for media files and lists them. Use the arrow keys to scroll, Space to toggle individual files, and a to select/deselect all recognised files at once.
4. Press Enter to build the rename preview. If any two files would produce the same output name, a conflict resolution step appears first — press 1, 2, or 3 to choose which file to keep or to skip the group entirely.
5. Review the preview, then press Enter to confirm. Press y or Enter at the final prompt to execute the renames.
6. A results summary is shown. Press any key to return to the menu.

Templates

Templates control how files are renamed. Two templates are stored in ~/.tidyflix/config.json and can be edited from the Settings screen inside the app.

| Setting | Default | |---|---| | TV template | {NAME} - S{SS}E{EE} | | Movie template | {NAME} ({YEAR}) |

Available tokens

TV shows

| Token | Description | Example | |---|---|---| | {NAME} | Series title | Star Trek | | {YEAR} | Release year | 1966 | | {SS} | Season, zero-padded | 01 | | {S} | Season number | 1 | | {EE} | Episode, zero-padded | 05 | | {E} | Episode number | 5 | | {QUALITY} | Video quality | 1080p | | {EPISODE_NAME} | Episode title (requires API key) | The Enemy Within |

Movies

| Token | Description | Example | |---|---|---| | {NAME} | Movie title | The Matrix | | {YEAR} | Release year | 1999 | | {QUALITY} | Video quality | 1080p |

Press ? from the Settings screen to open the token reference screen inside the app.

Settings

Open Settings from the home menu.

• TV template / Movie template — navigate to the row and press Space to open the inline editor. Type your template and press Enter to save. Unknown tokens are rejected with an error.
• Metadata provider — navigate to the row and press Space to toggle between TMDb and OMDB.
• API key — navigate to the row and press Space to enter or update your API key for the active provider.

Press Esc to cancel an edit or to go back to the home screen.

Metadata providers

TidyFlix can fetch episode names from external sources. Configure the provider and API key in Settings.

• TMDb — themoviedb.org. Free API key available after registration.
• OMDB — omdbapi.com. Free tier available.

The {EPISODE_NAME} token is only populated when a provider is configured with a valid API key.

When the filename parser can't determine all required fields, TidyFlix will query the metadata provider to fill in the gaps. If the search returns multiple candidates, a disambiguation picker is shown so you can select the correct title before the rename proceeds.

Update notifications

If a newer version of TidyFlix is available on npm, a notification is shown at the bottom of the home screen with the upgrade command:

Update available: 1.0.0 → X.Y.Z  (npm i -g tidyflix)

Config file

Settings are stored at ~/.tidyflix/config.json. The file is created automatically on first run. You can edit it directly if preferred — TidyFlix reads it fresh on each launch.

TidyFlix Community

The community for discussions, bug reports and feature requests can be found here.

Report an issue

Report an issue here.

Feature requests

Request a feature here