mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-12 03:56:53 +03:00
5.5 KiB
5.5 KiB
name, description, license, compatibility, metadata
| name | description | license | compatibility | metadata | ||||
|---|---|---|---|---|---|---|---|---|
| tmdb-cli | Search and discover movies, TV shows, and trending content via The Movie Database (TMDb) API v3. Use when the user asks about movies, TV, film, cinema, genres, certifications, ratings, cast, upcoming releases, or trending media. | MIT | Requires TMDB_ACCESS_TOKEN or TMDB_API_KEY env var (free at themoviedb.org/settings/api), Python 3.8+, and the `requests` library. |
|
tmdb-cli — Movie & TV Discovery from the Terminal
Search movies and TV shows by keyword, discover by genre/certification/rating/date, check trending and upcoming releases, browse genre lists, and view US certification ratings — all from TMDb's v3 API.
Setup
- Get a free API key or access token at themoviedb.org/settings/api
- Set one of these environment variables:
export TMDB_ACCESS_TOKEN="your-tmdb-access-token" # preferred
# OR
export TMDB_API_KEY="your-tmdb-api-key"
--help and --dry-run work without credentials (lazy auth).
Essential Commands
movie search — Search movies by keyword
tmdb-cli movie search --term "dune" # basic search
tmdb-cli movie search --term "inception" --limit 5 # top 5 results
tmdb-cli movie search --term "arrival" --json # machine-readable
Shows: title, release year, vote average.
movie discover — Discover movies by genre, certification, rating, and date
tmdb-cli movie discover --genre horror # horror movies
tmdb-cli movie discover --genre horror --certification R # horror, R-rated
tmdb-cli movie discover --genre comedy --rating 7 --limit 15 # highly-rated comedy
tmdb-cli movie discover --from 2024-01-01 --to 2024-12-31 # released in 2024
tmdb-cli movie discover --genre scifi --from 2026-05-01 # recent sci-fi
tmdb-cli movie discover --genre thriller --certification R \
--rating 6 --from 2025-01-01 --limit 20 # compound filter
movie upcoming — Upcoming movie releases
tmdb-cli movie upcoming # next 10 upcoming
tmdb-cli movie upcoming --limit 20 # more results
tmdb-cli movie upcoming --json # machine-readable
tv search — Search TV shows by keyword
tmdb-cli tv search --term "severance" # basic TV search
tmdb-cli tv search --term "the expanse" --limit 5
tmdb-cli tv search --term "silo" --json
Shows: name, first air year, vote average.
tv discover — Discover TV shows by genre, rating, and air date
tmdb-cli tv discover --genre sci-fi # sci-fi shows
tmdb-cli tv discover --genre drama --rating 7 # critically-acclaimed drama
tmdb-cli tv discover --genre comedy --from 2025-01-01 # recent comedy
trending — Trending content across day or week
tmdb-cli trending # trending movies this week
tmdb-cli trending --type tv # trending TV this week
tmdb-cli trending --type all --window day # all media trending today
tmdb-cli trending --limit 20 --json # top 20 as JSON
genre list — Browse available genres
tmdb-cli genre list --type movie # all movie genres
tmdb-cli genre list --type tv # all TV genres
tmdb-cli genre list --type movie --json
certification — View US movie certification ratings
tmdb-cli certification # US certification list
tmdb-cli certification --json # machine-readable
Global Flags
These flags work in any position before, between, or after subcommands:
tmdb-cli --json movie search --term "dune" # JSON output
tmdb-cli movie search --term "dune" --json # json after subcommand
tmdb-cli --dry-run movie discover --genre horror # preview without API call
tmdb-cli --quiet trending # suppress diagnostic output
tmdb-cli --verbose movie search --term "alien" # verbose logging
Known Gotchas
- Genre name matching is case-insensitive —
--genre Horror,--genre horror, and--genre HORRORall work. Names are matched via substring, so--genre scimatches "Sci-Fi" and "Science Fiction". - Certifications are US-only — The
--certificationflag and thecertificationsubcommand only return/accept US ratings (G, PG, PG-13, R, NC-17). International certifications are not available. - API version — This CLI wraps TMDb API v3. Endpoints and response shapes follow the v3 spec.
- Pagination defaults — Every command defaults to 10 results. Use
--limitto get more. The CLI does not auto-paginate beyond the first page. - Now-playing is defined — The
movie now-playingsubcommand is registered in argparse and maps to the TMDb/movie/now_playingendpoint.
References
- scripts/tmdb-cli — The CLI binary. Built following the cli-builder patterns: non-interactive,
--json,--dry-run,--quiet,--verbose, dual-output viaemit(), lazy auth, structured logging. - TMDb API v3 Reference — Official API documentation.
- TMDb API Settings (get a key) — Free API key registration.