Build a Todo CLI with TypeScript and Commander.js

What you will build

By the end of this tutorial you will have a working command-line app called todo with three subcommands: add <task> to add an item, list to print everything, and done <id> to check one off. Data persists between runs in a todos.json file in the project folder, so your list is still there when you come back tomorrow.

Every item is a typed TodoItem, so the code that creates a task and the code that prints it agree on the exact fields, and TypeScript flags any place you drift. Commander.js does the argument parsing: it reads the subcommand and its arguments, generates a --help screen for free, and prints a clear error when someone types a command that does not exist. That is the part worth learning, because it is the same pattern behind tools you already use like git and npm.

Every file you need is in this page. Paste each one into a fresh project, follow the setup steps, and it runs. No repo to clone.

Setup

Create a fresh project and install the tooling. Commander.js is the only runtime dependency; TypeScript, tsx, and @types/node are dev tooling for building and running the .ts files. Commander ships its own type definitions, so there is no separate @types/commander to install.

mkdir todo-cli
cd todo-cli
npm init -y && npm install commander && npm install -D typescript tsx @types/node

Add a tsconfig.json at the project root. These settings run cleanly with tsx in development and compile with tsc for a production build:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "rootDir": "src",
    "outDir": "dist",
    "types": ["node"]
  },
  "include": ["src"]
}

The "types": ["node"] line pulls in the Node.js type definitions from @types/node, so process, node:fs, and the other Node globals type-check when you build. Then open package.json, add "type": "module", and set these three scripts. dev runs the app directly with tsx (no build step while you work), build compiles to dist/, and start runs the compiled output:

{
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

The three source files below all go in a src/ directory you create in the project root.

Define the data type and storage helpers

Start with the shape of the data. One TodoItem interface, shared everywhere, keeps the app consistent: id to reference a task, task for the text, and done for whether it is finished.

Create src/types.ts:

export interface TodoItem {
  id: number;
  task: string;
  done: boolean;
}

Now the storage layer. Two functions read and write the list as JSON on disk. The one detail that trips people up is the first run: the todos.json file does not exist yet, so readFileSync throws an ENOENT error. Catch that specific case and return an empty list; rethrow anything else so a real problem (a corrupt file, a permissions error) does not fail silently.

Create src/store.ts:

import { readFileSync, writeFileSync } from "node:fs";
import type { TodoItem } from "./types.js";

const DB_FILE = "todos.json";

export function loadTodos(): TodoItem[] {
  try {
    return JSON.parse(readFileSync(DB_FILE, "utf8")) as TodoItem[];
  } catch (err) {
    // First run: the file does not exist yet, so start with an empty list.
    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
    throw err;
  }
}

export function saveTodos(todos: TodoItem[]): void {
  writeFileSync(DB_FILE, JSON.stringify(todos, null, 2));
}

Writing with JSON.stringify(todos, null, 2) keeps the file indented and readable, so you can open todos.json and see exactly what the app stored. The import ... from "./store.js" uses a .js suffix even though the file is store.ts: that is the ES module convention, and it is what lets the same import work under tsx in development and plain Node after you build.

Wire up Commander.js

Now the part that makes it a real CLI. Import Command from commander, create one program, and register a subcommand for each action. Each .command("add <task>") declares its name and its required argument in one string; Commander parses the input, hands your .action() callback the argument, and rejects anything malformed with a helpful message. The angle brackets mean the argument is required, so todo add with no text prints a usage error instead of adding a blank task.

Create src/index.ts:

#!/usr/bin/env node
import { Command } from "commander";
import { loadTodos, saveTodos } from "./store.js";
import type { TodoItem } from "./types.js";

const program = new Command();

program
  .name("todo")
  .description("A tiny persistent todo list for your terminal")
  .version("1.0.0");

program
  .command("add <task>")
  .description("Add a new task")
  .action((task: string) => {
    const todos = loadTodos();
    const id = todos.reduce((max, t) => Math.max(max, t.id), 0) + 1;
    const item: TodoItem = { id, task, done: false };
    todos.push(item);
    saveTodos(todos);
    console.log(`Added #${id}: ${task}`);
  });

program
  .command("list")
  .description("List all tasks")
  .action(() => {
    const todos = loadTodos();
    if (todos.length === 0) {
      console.log('No tasks yet. Add one with: todo add "your task"');
      return;
    }
    for (const t of todos) {
      const mark = t.done ? "[x]" : "[ ]";
      console.log(`${mark} #${t.id} ${t.task}`);
    }
  });

program
  .command("done <id>")
  .description("Mark a task as done")
  .action((id: string) => {
    const todos = loadTodos();
    const item = todos.find((t) => t.id === Number(id));
    if (!item) {
      console.error(`No task with id ${id}.`);
      process.exitCode = 1;
      return;
    }
    item.done = true;
    saveTodos(todos);
    console.log(`Marked #${item.id} done: ${item.task}`);
  });

program.parse();

Two things worth calling out. The id is Math.max(...existing ids) + 1, not todos.length + 1: reusing the length would hand out a duplicate id after you delete an item, so the max approach stays correct as the list changes. And Commander passes every argument as a string, so done <id> gives you id as text; Number(id) converts it before the lookup. When no id matches, the command sets a non-zero exit code, which is what a shell script wrapping your tool checks to know it failed.

Run and test it

While you develop, run the app straight from the TypeScript source with tsx. Add a couple of tasks, list them, then check one off:

npx tsx src/index.ts add "Learn TypeScript"
# -> Added #1: Learn TypeScript

npx tsx src/index.ts add "Build a CLI"
# -> Added #2: Build a CLI

npx tsx src/index.ts list
# -> [ ] #1 Learn TypeScript
# -> [ ] #2 Build a CLI

npx tsx src/index.ts done 1
# -> Marked #1 done: Learn TypeScript

npx tsx src/index.ts list
# -> [x] #1 Learn TypeScript
# -> [ ] #2 Build a CLI

Open todos.json in the project folder and you will see the same data on disk, which is why the list survives between runs. Commander also gave you a help screen for free: run npx tsx src/index.ts --help and it lists every subcommand and its description.

Build for production

To install the tool so you can type todo from any directory, compile it and point package.json at the output. Run the build first:

npm run build
# compiles src/*.ts to dist/*.js

Then add a bin field to package.json mapping the command name to the compiled entry file. The #!/usr/bin/env node shebang at the top of src/index.ts (TypeScript keeps it in the output) is what lets the operating system run the file directly:

{
  "type": "module",
  "bin": {
    "todo": "dist/index.js"
  },
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Now run npm link once to symlink the command onto your PATH, and call it like any installed tool:

npm link
# links the "todo" command globally

todo add "Ship the tutorial"
# -> Added #1: Ship the tutorial

todo list
# -> [ ] #1 Ship the tutorial

One thing to know: todo reads and writes todos.json in whatever directory you run it from, so your list is per-folder. That is often what you want for a project-scoped todo list. If you would rather have one global list, change DB_FILE in src/store.ts to an absolute path under your home directory.

Next steps

You have a working, typed CLI with real persistence. A few small additions turn it into something you would actually use.

Add a `delete <id>` command. It is almost identical to done: find the item, then splice it out of the array and save. Add a `--all` flag to `done` so todo done --all clears the whole list in one call; Commander reads flags with .option("--all"). Swap the JSON file for SQLite with better-sqlite3 once the list gets long enough that rewriting the whole file every save feels wasteful; the loadTodos/saveTodos split means only src/store.ts changes.

For deeper TypeScript study, our free TypeScript courses guide ranks the best free options, the TypeScript cheat sheet is a handy reference while you build, and Build a CLI tool for free lists more free courses on this exact topic.