Built a Rust trakt-cli with full API coverage, JSON-first output, and an agent-friendly SKILL.md

Discussions General
1

Hey everyone — I wanted to share a project I built around the Trakt API: trakt-cli, a native CLI written in Rust with a command structure that maps closely to thewas simple at first: make it easier to explore and work with Trakt’s large API surface from the terminal. It ended up becoming a practical way to navigate and use what the README describes as 100% Trakt.tv API coverage, with support for metadata, discovery, social features, calendars, sync, comments, notes, recommendations, and more.

One of the main use cases is just API discoverability. Trakt has a lot of endpoints, and when you are building something non-trivial it can take time to figure out which route or payload shape you actually need. I originally built this CLI to help myself navigate that API surface more efficiently while working on deeper Trakt integrations in my other project, NEXIO. Nexio is an Android TV media player and web portal project, with native Trakt integration for auth, scrobble, check-in, and account-managed catalogs including popular community lists as catalogs without third party add-ons.

That is also where I think trakt-cli may be useful to other developers: not just for quick terminal lookups, but as a development companion when prototyping Trakt-powered features. A few examples:

  • exploring movie/show metadata and relationships

  • checking calendars, premieres, finales, and release schedules

  • working with user collections, watchlists, favorites, ratings, and history

  • inspecting lists, community activity, comments, and recommendations

  • testing write flows like comments, notes, sync operations, scrobbles, and check-ins

  • resolving the right endpoint and request shape before wiring it into an app or service

Another focus was making it useful for AI agents and automation, not just humans at a shell. The repo README highlights JSON output specifically so results can be piped into tools like jq or other automation workflows, and the repository also includes a custom SKILL.md aimed at helping agents understand when and how to use the CLI effectively. That means the tool is designed not only for direct CLI usage, but also for agentic workflows where structured output and explicit command patterns matter.

On the implementation side, I chose Rust so the tool could be native and multi-platform. The latest release shown on GitHub is v1.1.0 from March 9, 2026 and includes Windows, Linux and MacOS binaries.

If anyone here is building against Trakt and wants a terminal tool for exploring the API, testing flows, or integrating Trakt into agent/automation setups, I’d love feedback.

Projects:

  • * trakt-cli: GitHub repo in Rust with full CLI surface and SKILL.md for agents.

  • * NEXIO: my media streamer / Android TV player project, where deeper Trakt integration was one of the motivations behind building the CLI in the first place.

If useful, I can also post a few concrete examples of workflows like:

  • finding the right endpoints for watchlist/favorites/catalog features

  • testing sync payloads

  • using the CLI in JSON mode with scripts or agents

2 Likes
2

Example use-case that I used to optimize and fix some of my Continue Watching behavior, here is my AI agent prompt:

Our Continue Watching improvements are lacking a bit. I have witnessed that application restarts not correctly preserve and load the continue watching trakt data from calendars/my/shows/{start_date}/{days} from the cache the same way Trakt and MDBList catalogs are pulled. Another issue I have found is that when I clear progress on a show, the show might briefly disappear from my feed but then come right back. When we clear progress on a show, it should reset all watched data on that entire show, remove the item from our cache, and trigger a immediate feed refresh in the background to the cache (which is pushed to the foreground once complete and should no longer have the removed item due to resetting the progress). To validate trakt api’s you can test the api path’s with the trakt-cli-agent skill to find the right API path, do not clear progress on live data, but you are free to set some show as watched that I’m not watching and test the clear progress on it, while at the same time fetching calendars/my/shows/{start_date}/{days} before and after to validate the API endpoints work as expected. Do not implement any trakt api changes unless we have validated them with the trakt-cli-agent SKILL, the skill is installed and the cli tool is in path

How the AI agent used the CLI to determine exact API paths:

I’ve isolated the likely code roots (ContinueWatchingSnapshotService auth/cache
behavior and show-removal path in TraktProgressService.removeFromHistory). I’m
now validating the exact Trakt behavior with trakt-cli before making API 
changes.

The CLI supports --json for calendars and sync add-history/remove-history with 
JSON payloads, so we can validate safely. I’m now extracting a test candidate 
from all-shows that is not currently in your my-shows window, then I’ll 
add+remove history on just that test show.

I found a safe test candidate not currently in your my-shows window: show 
The Heat (trakt show id 316908, episode S1E2, episode id 14022227). I’m now 
running a before/add/after/remove/after check on that one item only.

The add-history write succeeded (episodes:1). I’m fetching my-shows again to 
confirm this test show appears, then I’ll validate full-show reset via sync 
remove-history using a show-level payload.

Final plan:

I’ve confirmed the Trakt behavior with trakt-cli-agent: show-level history removal works with {“shows”:[{“ids”:{“trakt”:…}}]} and removes the show from calendars my-shows after refresh.

Implementation plan:

Gate ContinueWatchingSnapshotService writes until the first real Trakt remote snapshot loads, so startup cache isn’t overwritten by transient empty flows.

Add an explicit show-reset path (clearShowProgress) in the progress repository/service that:

removes episode playback for the show

removes full show history via Trakt sync/history/remove with a show payload

removes the show from in-memory calendar/progress state

triggers immediate Trakt refresh

Change continue-watching remove behavior for TV NextUp cards to use this show-reset path instead of mere dismiss, and force an immediate snapshot refresh.

Compile-check the app module and report exactly what changed.

3

Excellent ! I starred the project and will follow it!

Thanks for the tool!