trakt-timefix

A CLI tool to fix Trakt.tv watch history entries with incorrect dates. It changes entries watched before a specified cutoff date to "unknown" (no specific watched date).

Why?

Trakt didn't always have the option to mark entries as watched with an "unknown" date. Back then, many users (myself included) entered watch history using placeholder dates like release dates or arbitrary past dates. Now that Trakt supports "unknown" as a watched date option, this tool lets you bulk-fix those old entries.

It automates the process by:

1. Finding all movies and episodes watched before your cutoff date
2. Removing those entries from your history
3. Re-adding them with an "unknown" watched date

Requirements

• Bun v1.0 or later
• A Trakt.tv account
• Trakt API credentials

Installation

git clone https://github.com/alysson-souza/trakt-fixer.git
cd trakt-fixer
bun install

Setup

1. Create a Trakt API Application

1. Go to Trakt API Applications
2. Fill in the application details:
   • Name: trakt-timefix (or whatever you prefer)
   • Redirect URI: urn:ietf:wg:oauth:2.0:oob
3. Save and note your Client ID and Client Secret

2. Set Environment Variables

# bash/zsh
export TRAKT_CLIENT_ID="your_client_id"
export TRAKT_CLIENT_SECRET="your_client_secret"

# fish
set -x TRAKT_CLIENT_ID "your_client_id"
set -x TRAKT_CLIENT_SECRET "your_client_secret"

Or create a .env file (Bun loads it automatically):

TRAKT_CLIENT_ID=your_client_id
TRAKT_CLIENT_SECRET=your_client_secret

Usage

bun start -- --cutoff <date> [options]

Options

Option	Description
--cutoff <date>	Entries watched before this date will be fixed (ISO format: 2020-01-01). Defaults to Trakt join date
--dry-run	Preview changes without modifying anything
--no-backup	Skip backup creation
--no-cache	Force fresh fetch, ignore cached data
-h, --help	Show help message

Examples

Preview what would be changed:

bun start -- --cutoff 2015-01-01 --dry-run

Fix all entries before 2015:

bun start -- --cutoff 2015-01-01

Force fresh data fetch:

bun start -- --cutoff 2015-01-01 --no-cache

Use your Trakt join date as cutoff (auto-detected):

bun start -- --dry-run

Restoring from Backup

If you need to undo changes and restore original watched dates:

# List available backups
bun run undo -- --list

# Restore from most recent backup
bun run undo

# Preview restoration without making changes
bun run undo -- --dry-run

# Restore from a specific backup file
bun run undo -- --backup ~/.config/trakt-timefix/backup-2024-01-15T10-30-00.json

Authentication

On first run (or when tokens expire), you'll be prompted to authenticate:

1. The tool will display a URL and a code
2. Visit the URL in your browser
3. Enter the code and authorize the application
4. The tool will automatically continue once authorized

Tokens are stored locally and refreshed automatically when needed.

Data Storage

Data is stored in a platform-specific config directory:

Platform	Location
Linux	~/.config/trakt-timefix/
macOS	~/Library/Application Support/trakt-timefix/
Windows	%APPDATA%\trakt-timefix\

On Linux and macOS, XDG_CONFIG_HOME is respected if set.

Files stored:

File	Description
tokens.json	OAuth tokens (auto-refreshed)
cache.json	Cached history data (1h TTL, auto-refreshed)
backup-*.json	Backups of modified entries

Safety Features

• Dry run mode: Preview changes before applying
• Automatic backups: Entries are backed up before modification
• Confirmation prompt: Asked before making changes
• Caching: Reduces API calls and allows quick re-runs
• Rate limit handling: Respects Trakt API limits with automatic retries

Development

# Run tests
bun test

# Run tests in watch mode
bun test --watch

# Lint code
bun run lint

# Format code
bun run format

License

MIT