Building a TMDB CLI Tool: Fetch Movie Info Straight from Your Terminal

TMDB Logo

I created a CLI tool as part of the roadmap.sh TMDB CLI project to sharpen my Node.js skills, handle API requests, and manage command-line arguments. The result? A lightweight app that delivers movie info in seconds, with clean, formatted output. No fluff, just the essentials like titles, release dates, original languages, and more.

As a movie enthusiast and developer, I often find myself wanting quick access to movie information without opening the browser. That’s why I built this simple Command-Line Interface (CLI) tool using Node.js to interact with The Movie Database (TMDB) API, so that I can check movies from the terminal while coding. I’ll walk you through the project, explain how it works, and show you how you can set it up yourself.

The Movie Database (TMDB) is one of the most comprehensive resources for movie and TV data, powering apps like IMDb and Letterboxd. Their API is free and robust, making it perfect for personal projects.

The Idea

The key idea is to have easy access to movies that are currently popular or the top upcoming films. Instead of opening a browser and surfing the web, checking from the terminal is far less distracting. So, typing the command like this:

tmdb --type popular

will fetch the popular movies and display them in the console.

The goal is simple: Validate the commands and input flags, fetch movie data from the TMDB API, and display them neatly in the terminal, handle errors gracefully, and keep the tool lightweight and fast.

The Tech Stack

This project was written in Node.js. External libraries used in this project are:

• Commander.js: For command-line argument parsing
• dotenv: to handle environment variables securely

Project Structure

I kept the folder structure clean and simple:

tmdb-cli/
├── bin/
│   └── bin.js             # CLI entry point
├── cli/
│   └── cli.js             # Command parsing and validation
├── utils/
│   └── formatOutput.util.js
├── index.js               # Main logic
├── package.json
└── .env                   # API key

Setting Up TMDB API Key

1. Head to The Movie Database and create an account if you don’t have one.
2. Navigate to your account settings > API > Create API Key.
3. Copy your API key.

Next, set it as an environment variable. Create a .envfile in the project root:

TMDB_API_KEY=your_api_key_here

Pro Tip: Add .env to your .gitignore to keep your key private.

On macOS/Linux:

export TMDB_API_KEY=your_api_key_here

On Windows (Command Prompt):

set TMDB_API_KEY=your_api_key_here

The tool will check for this key and validate it with a test request to TMDB’s configuration endpoint.

Parsing CLI Arguments

I used Commander.js to parse the CLI arguments instead of process.argv to simplify the process.

import { Command } from "commander";

const program = new Command();
program
  .name("tmdb")
  .description("A CLI tool to get tmdb info")
  .option("--type <category>", "Specify the type", (type) => {
    const validFlags = ["popular", "top_rated", "upcoming", "playing"];
    if (!validFlags.includes(type)) {
      console.error(
        `Invalid type: ${type}. Valid types are: ${validFlags.join(", ")}`
      );
      process.exit(1);
    }
    return type;
  });

program.parse(process.argv);

const options = program.opts();
if (!options.type) {
  console.error("Error: --type option is required.");
  process.exit(1);
}
export default options;

If you type something invalid, the CLI immediately tells you what went wrong:

Invalid type: trending. Valid types are: popular, top_rated, upcoming, playing

Fetching Data from TMDB

Each category corresponds to one of TMDB’s REST API endpoints. Here’s a simplified snippet of how the requests are made:

const reqOptions = {
  method: "GET",
  headers: {
    accept: "application/json",
    Authorization: `Bearer ${process.env.TMDB_API_KEY}`,
  },
};

const res = await fetch("https://api.themoviedb.org/3/movie/popular", reqOptions);
const data = await res.json();

I also included a connectivity check at the start, so if you’re offline, it immediately notifies you instead of throwing a network error.

Output Formatting

Raw JSON is messy to read in the terminal, so I used grouped console output for a structured view.

export default function formatOutput(movies) {
  movies.results.forEach((movie) => {
    console.groupCollapsed(`- ${movie.title} (Release Date: ${movie.release_date})`);
    console.log(`  Original Language: ${movie.original_language}`);
    console.log(`  Original Title: ${movie.original_title}`);
    console.groupEnd();
  });
}

Example output:

Fetching popular movies from TMDB...
Popular Movies
- Dune: Part Two (Release Date: 2024-02-29)
  Original Language: en
  Original Title: Dune: Part Two
- Oppenheimer (Release Date: 2023-07-19)
  Original Language: en
  Original Title: Oppenheimer

It’s clean, readable, and doesn’t feel like raw API data anymore.

CLI Entry Point

For CLI, include the following code in cli/cli.js file:

#!/usr/bin/env node
import tmdb from "../index.js";
tmdb();

then, in package.json , add the bin property:

"bin": {
    "tmdb": "./bin/bin.js"
  },

After that, run npm link to link it globally for easy access. Voila, we are ready to use the CLI tool.

Note: It is important to include the proper shebang #!/usr/bin/env node at the beginning of the CLI entry point; otherwise, the script will not use node to execute the program and will throw an error.

Example: Fetching Popular Movies

Run:

tmdb --type popular

Sample Output:

Fetching popular movies from TMDB...
Popular Movies
  - Guardians of the Galaxy Vol. 3 (Release Date: 2023-05-03)
    Original Language: en
    Original Title: Guardians of the Galaxy Vol. 3
  - Spider-Man: Across the Spider-Verse (Release Date: 2023-06-02)
    Original Language: en
    Original Title: Spider-Man: Across the Spider-Verse
  ...

Try It Yourself

You can try the project locally from GitHub:

git clone <your-repo-url>
cd tmdb-cli
npm install
npm link
tmdb --type popular

What’s Next

Some ideas I might explore next:

• Add --search <movie> or --search <person>to find movies by name or actor
• Paginate results or limit with --limit
• Colorize output with chalk
• Cache results locally to avoid repeated API calls

Final Thoughts

Sometimes the simplest projects are the most satisfying. This CLI started as a quick experiment to play with TMDB’s API, and ended up as a polished, reusable tool that’s both practical and fun to use.

If you enjoy tinkering with APIs, I definitely recommend building a CLI tool like this. It’s an excellent exercise in combining networking, environment management, and user experience in one compact Node.js project. Follow my GitHub for more fun projects like this. See you in the next project!