TaskForge CLI

A lightweight, no-nonsense task manager for developers who live in the terminal.

Why TaskForge?

Because sometimes you don't want to open a browser tab, launch an Electron app, or deal with another SaaS subscription just to remember that you need to buy milk. TaskForge is a CLI tool that stays out of your way — it's fast, portable, and lives wherever your terminal is.

This is an early prototype (v0.1.0). The goal is to build a focused, minimal task manager that does one thing well: help you track what you need to do.

Quick Start

Installation

# Clone the repo
git clone https://github.com/taskforge/taskforge-cli.git
cd taskforge-cli

# Install (development mode)
pip install -e .

Basic Usage

# Add a task
taskforge add "Write documentation" --priority high

# List all tasks
taskforge list

# List only incomplete tasks
taskforge list --status todo

# Mark task as done
taskforge done abc12345

# Get task details
taskforge get abc12345

# Update a task
taskforge update abc12345 --title "Updated title" --priority high

# Search tasks
taskforge search "meeting"

# Delete a task
taskforge delete abc12345

# View statistics
taskforge stats

# Clear all tasks (careful!)
taskforge clear --force

Demo Output

$ taskforge add "Deploy to production" -p high -t deploy -t urgent
Task created: [a1b2c3d4] Deploy to production

$ taskforge list
ID         STATUS       PRIORITY TITLE
----------------------------------------------------------------------
a1b2c3d4   [ ]          high     Deploy to production

$ taskforge done a1b2c3d4
Task marked as done: [a1b2c3d4] Deploy to production

$ taskforge stats
========================================
           TaskForge Statistics
========================================
  Total Tasks:     1
----------------------------------------
  Todo:           0
  In Progress:    0
  Done:           1
  Cancelled:      0
========================================

  Completion: [==============] 100.0%

Project Structure

taskforge-cli/
├── src/
│   ├── __init__.py       # Package init
│   ├── __main__.py       # Entry point
│   ├── cli.py            # CLI interface & commands
│   ├── config.py         # Configuration
│   ├── exceptions.py     # Custom exceptions
│   ├── logger.py         # Logging utilities
│   ├── models.py         # Task data model
│   ├── repository.py     # CRUD operations
│   └── storage.py        # JSON persistence
├── setup.py              # Package setup
├── .gitignore            # Git ignore rules
└── README.md             # This file

Features

• Create tasks with title, description, priority, and tags
• Read tasks individually or as a list
• Update task properties on the fly
• Delete tasks (with confirmation)
• Search by title or description
• Status tracking: todo, in_progress, done, cancelled
• Priority levels: low, medium, high
• Tagging for organization
• Statistics dashboard
• Persistent storage using JSON (data stored in ~/.taskforge/)

Architecture

TaskForge follows a clean layered architecture:

CLI Layer        → cli.py (argument parsing, user I/O)
Repository Layer → repository.py (business logic, CRUD)
Storage Layer    → storage.py (JSON file persistence)
Model Layer      → models.py (Task dataclass, enums)

This separation keeps things testable and allows swapping storage backends later.

Data Location

Tasks are stored in:

~/.taskforge/tasks.json

Requirements

• Python 3.8+
• No external dependencies (pure stdlib)

Roadmap

• Add due dates and reminders
• Support multiple task lists/projects
• Add export (CSV, JSON)
• Add recurring tasks
• Fuzzy search
• Shell completion scripts
• Config file support
• Tests (pytest)

Contributing

This is a prototype, but issues and PRs are welcome. Keep it simple.

License

MIT