trakt
Discover and compare public Trakt.tv trending, popular, and anticipated movies and shows from the terminal. Do not use this skill for personal history, watchlist, collection, or list management; the bundled CLI has no user-scoped operations. Use `tmdb` for catalog metadata, credits, images, and provider lookups.
How do I install this agent skill?
npx skills add https://github.com/magnus919/agent-skills --skill traktIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The trakt skill is a legitimate API client for media discovery on Trakt.tv. It follows standard practices for authentication using environment variables and provides a CLI for fetching trending, popular, and anticipated media content.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Trakt media discovery
Use this skill to inspect what is being watched, what is broadly popular, and what is anticipated. It is a read-only discovery surface, not a catalog metadata service.
Setup and authentication
Register an app at Trakt OAuth applications and export its Client ID:
export TRAKT_CLIENT_ID="YOUR_TRAKT_CLIENT_ID"
Every request must send trakt-api-key: <client id> together with the mandatory companion header trakt-api-version: 2, plus JSON content type and a descriptive User-Agent. Public discovery endpoints use the key header, not Authorization: Bearer. OAuth bearer tokens are for endpoints marked OAuth-required or for user-scoped lists, history, collection, watchlist, and mutations; a bearer token does not replace the key/version pair.
Essential commands
All six discovery commands accept --page N alongside --limit N; both default to 1 and 10 respectively and are forwarded to the API's query string.
Trending: watched in the last 24 hours
trakt movie trending --limit 20
trakt tv trending --limit 20 --page 2 --json
Trending responses wrap each media object in movie or show and include a watchers count.
Popular: broad popularity ranking
trakt movie popular --limit 25 --json
trakt tv popular --page 2 --limit 25
Popular is a ranking based on rating percentage and number of ratings, not a personalized recommendation.
Anticipated: upcoming interest
trakt movie anticipated --page 3 --limit 10
trakt tv anticipated --limit 10 --json
Anticipated reflects list appearances and upcoming interest. It is not the same as a release calendar.
Global flags can appear before or after the resource: --json, --dry-run, --quiet, and --verbose.
Pipeline recipes
Trending handoff to another tool
- Run
trakt --json movie trending --limit 20. - Unwrap
.movie, retaining.watchersas the watch signal. - Pass an available
.movie.ids.tmdbor.movie.ids.imdbto a downstream tool; do not assume a missing ID can be synthesized.
trakt --json movie trending --limit 20 |
jq '.movies[] | {title: (.movie.title // .title), year: (.movie.year // null), watchers: (.watchers // null), ids: (.movie.ids // .ids)}'
Compare discovery signals
Fetch matching pages of trending, popular, and anticipated (e.g. --page 1 for each), then label each dataset before combining it. Trending is recent watching, popular is broad ranking, and anticipated is upcoming interest.
Page through anticipated until the feed ends
Loop --page, read pagination.page_count from JSON output to pick the stop page, and break early if a page returns no items:
for p in $(seq 1 "$(trakt --json movie anticipated --page 1 --limit 100 | jq -r '.pagination.page_count')"); do
trakt --json movie anticipated --page "$p" --limit 100 |
jq --arg p "$p" '{page: ($p|tonumber), pagination: .pagination,
movies: [.movies[] | {title: (.movie.title // .title), year: (.movie.year // null)}]}'
done
Keep per-page output as labeled NDJSON; merge afterwards. On 429, wait out Retry-After before continuing the loop.
JSON and pagination
--json emits an object with a movies or shows array (trending entries retain their wrapper) plus a pagination object whose keys mirror the API's X-Pagination-* headers: page, limit, page_count, item_count. Pagination keys are ints when the headers were present and the object is empty {} when they were absent, so jq like .pagination.page_count // 1 degrades safely. Human output appends a Page N of M line when the headers are present and stays silent otherwise. The API defaults to page 1 with limit 10 for compatibility; set both explicitly for reproducible automation, and stop at page_count rather than assuming a short page is the end.
Known gotchas
- Header pair is mandatory: sending
trakt-api-keywithouttrakt-api-version: 2(or vice versa) can yield an invalid-request/authentication-style failure. The bundled script injects both on every live request. - 401 versus 403: 401 commonly indicates an OAuth requirement or invalid authorization; 403 indicates an invalid or unapproved application key. Do not retry either blindly.
- Rate limits: on 429, honor
Retry-Afterand inspectX-Ratelimit. Use bounded retries; transient 502/503/504 responses may be retried with backoff. - OAuth refresh: access tokens last seven days and refresh tokens are single-use. Replace the stored refresh token after a successful refresh;
invalid_grantrequires reauthorization. - Trakt is not TMDb: Trakt IDs and discovery rankings are not TMDb metadata. Use the
tmdbskill for credits, images, provider metadata, and catalog enrichment. - Trending shape: read
.movieor.showbefore title/IDs, while preservingwatchers. - Pagination is per invocation: one CLI call fetches exactly one page (
--page); loop invocations readingpagination.page_countrather than expecting the script to follow links itself.
When to use
Use Trakt for current watching signals, broad popularity, anticipated interest, and identifiers that feed a media workflow.
When not to use
Do not use this CLI to read or update personal history, watchlists, collections, or lists. It implements neither those commands nor OAuth; supplying a token does not enable them. Explain the limitation and use the Trakt website or a separately implemented, authenticated client for personal operations. Do not invent CLI commands or claim a requested update succeeded. Use tmdb for catalog metadata, credits, images, and provider availability.
Reference files
| File | Topic |
|---|---|
| references/auth-and-request-contract.md | Required headers, OAuth boundary, errors, and rate limits |
| references/discovery-endpoints.md | Endpoint semantics, filters, response shapes, and pagination |
| references/recipes-and-operations.md | Pipelines, jq normalization, and operational handling |
Available script and prerequisites
scripts/traktis an executable Python CLI using only stdlib andrequests.--dry-runworks without a Client ID and never performs network I/O.- Live discovery requires
TRAKT_CLIENT_ID; tests are mock-only.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/magnus919/agent-skills/trakt">View trakt on skillZs</a>