trakt-plugin

README

trakt-plugin

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

A CLI and AI agent plugin for Trakt.tv using the Trakt API. Search movies and shows, view watch history, manage your watchlist, track show progress, 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 openclaw-trakt

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

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

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_watchlist, trakt_progress, and trakt_auth.

Install from NPM:

openclaw plugins install openclaw-trakt

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