A cookie-authenticated command-line client for IMDb. Search titles and manage your watchlist, watched status, and ratings straight from the terminal.

IMDb has no official public write API, so this tool authenticates the same way your browser does — using your logged-in session cookies — and talks to IMDb's internal search and GraphQL endpoints.

Disclaimer: This is an unofficial tool, not affiliated with or endorsed by IMDb or Amazon. Use it with your own account and in accordance with IMDb's Conditions of Use. IMDb data is provided for personal, non-commercial use.

• search — find titles/names (no login required)
• watchlist add|remove — manage your Watchlist
• watched add|remove — mark/unmark titles as watched
• rate <1-10> / rate --delete — set or remove your rating
• Plain-text or --json output for scripting

git clone https://github.com/Rahulsharma0810/imdb-cli.git
cd imdb-cli
npm install
npm run build
npm link   # optional: puts `imdb` on your PATH

Requires Node.js >= 18 (uses the built-in fetch).

Write actions need your IMDb session cookies. Export them from a browser where you are logged in to imdb.com, in the Netscape cookie file format (browser extensions such as Get cookies.txt LOCALLY do this).

The CLI looks for the cookie file in this order:

1. --cookies <path> flag
2. IMDB_COOKIES environment variable
3. ~/.config/imdb-cli/cookies.txt
4. ./www.imdb.com_cookies.txt

mkdir -p ~/.config/imdb-cli
cp ~/Downloads/www.imdb.com_cookies.txt ~/.config/imdb-cli/cookies.txt

Note: IMDb's session-token cookie rotates periodically. If a command fails with a FORBIDDEN / "Authentication required" error, re-export your cookies from the browser.

# Search (no login needed)
imdb search amelie
# tt0211915  Amélie (2001) [feature]

# Add to watchlist
imdb watchlist add tt0211915

# Mark as watched
imdb watched add tt0211915

# Rate 8/10 (also marks the title watched)
imdb rate tt0211915 8

# Remove things
imdb watchlist remove tt0211915
imdb rate tt0211915 --delete
imdb watched remove tt0211915

# JSON output for scripts
imdb --json search "the matrix" -n 3

Rating a title on IMDb automatically marks it as watched. Because of this, to return a title to a fully un-watched state you must delete the rating first and then remove the watched flag:

imdb rate tt0211915 --delete
imdb watched remove tt0211915

Authentication is carried entirely by cookies — there is no API key or Authorization header.

npm run dev     # tsc --watch
npm run build   # compile to dist/

MIT © Rahul Sharma