cli-task-tracker (ctt)

A lightweight, non-overwhelming command-line task tracker written in C++23.

• Overview
• Features
• Installation
  • CMake
  • Download binaries
• Usage
• Examples
• Contributing & Support

Overview

ctt (cli-task-tracker) strives to provide a simple and intuitive interface, while being not so overwhelming and scary 👻 to explore. Tasks are stored locally in a JSON file, so there is no database setup, no accounts, and no internet connection required — just a single executable.

It was implemented as a Task Tracker pet-project, following the roadmap.sh project guidelines.

Features

Tasks are persisted in a local JSON file powered by the nlohmann/json library¹.

Here are the features given at your disposal:

• Add a new task with a short description
• Update the description of an existing task by its ID
• Delete a task that is no longer needed
• Mark tasks as in-progress or done to track your progress
• List all tasks at once, or filter them by their status (todo / in-progress / done)
• Built-in help — run task-cli help or task-cli help <command> for instant usage reference

Installation

CMake

You can build the binary from source using CMake (version 3.31.3 or later) and a C++23-capable compiler:

> git clone https://github.com/PavloShutz/cli-task-tracker.git
> cd cli-task-tracker
> cmake -B build
...
> cmake --build build

After a successful build, the task-cli executable will be placed inside the build/ directory.

Download binaries

If you prefer not to compile from source, head over to the Releases tab and download the pre-built executable for your platform.

Usage

After obtaining the executable (either by building or downloading), you can run it directly from its directory, or make it available system-wide:

• Windows — add the folder that contains task-cli.exe to your PATH environment variable.
• Linux / macOS — move (or symlink) the binary to a directory that is already on your PATH, such as /usr/local/bin:

sudo mv build/task-cli /usr/local/bin/task-cli

Once task-cli is on your PATH, every new terminal session can call it by name. Run task-cli (with no arguments) or task-cli help at any time to see the full list of available commands.

Examples

The walkthrough below shows the most common workflow: adding tasks, updating them, tracking their progress, and finally cleaning them up.

# Show the built-in help overview
D:\>task-cli
task-cli - A simple non-overwhelming command-line task tracker

Usage: task-cli <command> [arguments...]

Commands:
  add <description>             Add a new task.
  update <id> <description>     Update a task's description.
  delete <id>                   Delete a task.
  list [status]                 List tasks, optionally filtered by status.
  mark-in-progress <id>         Mark a task as in-progress.
  mark-done <id>                Mark a task as done.
  help [command]                Show help for a specific command.

# Get detailed help for a specific command
D:\>task-cli help add
Usage: task-cli add <description>

Options:
  <description>                 = A description of the task.

D:\>task-cli help update
Usage: task-cli update <id> <description>

Options:
  <id>                          = The ID of the task to update.
  <description>                 = A new description for the task.

# Add a couple of tasks
D:\>task-cli add "Buy groceries"

D:\>task-cli add "Read a book"

D:\>task-cli add "Go for a morning run"

# List all tasks — they all start with status "todo"
D:\>task-cli list
Task #0:
        "Buy groceries"
        status: "todo"
Task #1:
        "Read a book"
        status: "todo"
Task #2:
        "Go for a morning run"
        status: "todo"

# Update a task's description
D:\>task-cli update 1 "Read Clean Code by Robert C. Martin"

# Start working on a task
D:\>task-cli mark-in-progress 2

# List only the tasks that are currently in progress
D:\>task-cli list in-progress
Task #2:
        "Go for a morning run"
        status: "in-progress"

# Mark a task as done
D:\>task-cli mark-done 0

# List only completed tasks
D:\>task-cli list done
Task #0:
        "Buy groceries"
        status: "done"

# Delete a task that is no longer relevant
D:\>task-cli delete 0

# All remaining tasks after the deletion
D:\>task-cli list
Task #1:
        "Read Clean Code by Robert C. Martin"
        status: "todo"
Task #2:
        "Go for a morning run"
        status: "in-progress"

D:\>

Contributing & Support

Contributions of all kinds are warmly welcome! Whether it's a bug report, a feature suggestion, a documentation improvement, or a pull request — every bit of help makes this project better.

How to contribute:

1. Fork the repository and create your branch from main.
2. Make your changes, then open a pull request with a clear description of what you changed and why.
3. For larger changes, consider opening an issue first to discuss your idea.

Found a bug or have an idea? Open an issue — feedback is always appreciated.

If you find ctt useful, please consider giving the repository a ⭐ star on GitHub. It helps others discover the project and motivates further development. Thank you! 🙏

Footnotes

1. https://json.nlohmann.me/ ↩