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

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.

4

s sounds really impressive, and although I haven’t delved deep enough or am not technically proficient, I do have a product management perspective on this.

I believe the real issue is not so much extracting information from Trakt but inputting it. Although I have tracked VIP and synchronized with streaming applications, the number of titles is a fraction of what I have from my Apple TV data dump over the past seven years.

Apple provides extremely detailed information on every play, pause, title, movie, and episode, but it does not include an IMDb, TMDB, or other abbreviation ID. This is enough for Track VIP support to say they cannot help import any of that into the database. Although it is probably more in their interest than mine, to engage transformer models, you need large, statistically significant data, not from one user, but from many. It’s so easy to get much more detailed information than what I can see on Trakt, and I struggle to process it so that the few hundred titles I have from the past year are augmented by ten times from Apple TV history. This includes all connected apps except Netflix and a far more expanded time set. It’s available in CSV and JSON object format in the more abbreviated version (the expanded version includes every time you touch a remote, pretty much).

If you would like, I can send you samples of this, but I think this is the real game changer. We are all traumatized by the regression of the industry from Netflix, which customizes content to silos that operate in a post-traumatic stress disorder from the side of the providers and monopolies from the side of Apple, Google, and so on. That’s why they don’t make it extremely easy for you, but not that hard either, to get enormous amounts of information. For the patterns that are identified, you really need much more data across many more variables and a much larger number of people. Unlike transformer models in what they call AI, which become less accurate when they have dense vector databases that appear to provide answers they are unable to generate, but just guess based on the average of averages, in this case, the potential is to drop the endless rows and catalogs. At least for me, the aspiration is to have what I want, what I wanted. It’s really not about the quantity. It’s about the quality, and the lesser the quantity, the better. In speech and text analysis, transformer models operate unidirectionally, as opposed to RAG, which is an advantage when you need to just predict the next title based on all the history. The more you get, the more accurate you become. This is exactly the opposite of what is happening, and what they call AI and systems are becoming more and more hallucinating because their data is not reflective of information; it is reflective of the relationship between words in a sentence and patterns. And the proof of it in the "AI "pudding.- lots and lots of catalogue. It’s a definite improvement from the streaming industry, stagnation or rather aggression, but it’s a far cry from what it could be and sounds like what you’re doing would be perfect if I had the skills to implement ultimately the patterns in the document can be identified and extracted with what you’re doing I really I’m curious to hear back from you. Your thoughts?