Tmdb CLI

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

1. Get a free API key or access token at themoviedb.org/settings/api
2. 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 HORROR all work. Names are matched via substring, so --genre sci matches "Sci-Fi" and "Science Fiction".
• Certifications are US-only — The --certification flag and the certification subcommand 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 --limit to get more. The CLI does not auto-paginate beyond the first page.
• Now-playing is defined — The movie now-playing subcommand is registered in argparse and maps to the TMDb /movie/now_playing endpoint.

References

• scripts/tmdb-cli — The CLI binary. Built following the cli-builder patterns: non-interactive, --json, --dry-run, --quiet, --verbose, dual-output via emit(), lazy auth, structured logging.
• TMDb API v3 Reference — Official API documentation.
• TMDb API Settings (get a key) — Free API key registration.