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.