trakt-plugin

████████╗██████╗  █████╗ ██╗  ██╗████████╗     ██████╗██╗     ██╗
╚══██╔══╝██╔══██╗██╔══██╗██║ ██╔╝╚══██╔══╝    ██╔════╝██║     ██║
   ██║   ██████╔╝███████║█████╔╝    ██║       ██║     ██║     ██║
   ██║   ██╔══██╗██╔══██║██╔═██╗    ██║       ██║     ██║     ██║
   ██║   ██║  ██║██║  ██║██║  ██╗   ██║       ╚██████╗███████╗██║
   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝        ╚═════╝╚══════╝╚═╝

A CLI and AI agent plugin for Trakt.tv using the Trakt API. Search movies and shows, view and manage your watchlist (add/remove), view and edit watch history (add/remove), track show progress, check the upcoming-episodes calendar, and mark items as watched.

Ships as both a standalone Go CLI and as plugins for OpenClaw and Claude Code.

Installation

Go CLI

go install github.com/omarshahine/trakt-plugin@latest

Or grab a binary from the releases.

OpenClaw Plugin

openclaw plugins install trakt-tools

Claude Code Plugin

claude --plugin-dir /path/to/trakt-plugin

From Source

git clone https://github.com/omarshahine/trakt-plugin
cd trakt-plugin
go build -o trakt-cli .

Authentication

trakt-cli auth
Please go to https://trakt.tv/activate and enter the following code: XXXXXXXX
Successfully authenticated, creds written to ~/.trakt.yaml

The CLI ships with built-in OAuth credentials. To use your own Trakt API app instead, pass --client-id and --client-secret flags, or set TRAKT_CLIENT_ID and TRAKT_CLIENT_SECRET environment variables.

Commands

All commands support --json for machine-readable output.

search

Search for movies and TV shows.

trakt-cli search "Severance"
trakt-cli search "Inception" --type movie --json

Flag	Values	Default
--type	movie, show, movie,show	movie,show

history

View watch history.

trakt-cli history --json
trakt-cli history --type shows --limit 20
trakt-cli history --type movies --json

Flag	Description	Default
--type	movies or shows	all
--limit	Items per page	10
--page	Page number	1

history add

Mark movies or shows as watched. Searches by title and prefers exact matches.

trakt-cli history add "Severance" --json
trakt-cli history add "The Sopranos" "The Wire" --json
trakt-cli history add --type movie "The Godfather" --json
trakt-cli history add --watched-at 2025-06-15 "Dark" --json

Flag	Description	Default
--type	show or movie	show
--watched-at	YYYY-MM-DD or RFC3339	now

history remove

Undo a mark-as-watched. Removing a show wipes ALL its episode plays; removing a movie wipes all its watches. There is no per-watch granular removal — Trakt's API removes by trakt id, not by timestamp.

trakt-cli history remove "Severance" --json
trakt-cli history remove --type movie "The Godfather" --json

Flag	Description	Default
--type	show or movie	show

watchlist

View your watchlist.

trakt-cli watchlist --json
trakt-cli watchlist --type shows --limit 100
trakt-cli watchlist --type movies --json

Flag	Description	Default
--type	movies or shows	all
--limit	Items per page	10
--page	Page number	1

watchlist add

Add movies or shows to your watchlist. Searches by title and prefers exact matches. Items already on the list are reported under existing_* counts (not an error).

trakt-cli watchlist add "Severance" --json
trakt-cli watchlist add "The Bear" "Shrinking" --json
trakt-cli watchlist add --type movie "Oppenheimer" --json

Flag	Description	Default
--type	show or movie	show

watchlist remove

Remove movies or shows from your watchlist. Searches by title. Items that were not on the list are silent no-ops (deleted_*=0, not an error).

trakt-cli watchlist remove "Severance" --json
trakt-cli watchlist remove --type movie "Oppenheimer" --json

Flag	Description	Default
--type	show or movie	show

calendar

Show upcoming episodes of shows you watch. This is the only read command that returns forward-looking data — ideal for proactive "what airs next?" workflows.

trakt-cli calendar --json
trakt-cli calendar --days 14 --json
trakt-cli calendar --start 2026-04-10 --days 7 --json
trakt-cli calendar --new --days 30 --json  # series premieres only

Flag	Description	Default
--days	Number of days to look ahead	7
--start	Start date (YYYY-MM-DD)	today
--new	Only series premieres (S01E01 airings)	off

progress

Show watch progress for watchlist TV shows.

trakt-cli progress --json
trakt-cli progress --all --json

Flag	Description	Default
--all	Include not_started and completed	in-progress only

AI Agent Plugins

OpenClaw

The openclaw/ directory contains a native OpenClaw plugin that registers typed tools: trakt_search, trakt_history, trakt_history_add, trakt_history_remove, trakt_watchlist, trakt_watchlist_add, trakt_watchlist_remove, trakt_calendar, trakt_progress, and trakt_auth.

Install from ClawHub:

openclaw plugins install trakt-tools

Or locally:

openclaw plugins install -l ./openclaw

Configuration (via OpenClaw settings):

• cliPath: Path to trakt-cli binary (auto-detected on PATH)
• clientId: Trakt API client ID
• clientSecret: Trakt API client secret

Claude Code

The .claude-plugin/ and skills/ directories provide a Claude Code plugin with a skill that teaches Claude how to use the CLI.

claude --plugin-dir /path/to/trakt-plugin

Credits

Originally forked from angristan/trakt-cli. Extended with watchlist, progress, history add commands, --json output, and AI agent plugin packaging.

License

MIT