Todo CLI

A powerful command-line todo manager with time tracking, project management, and comprehensive reporting.

TL;DR

# Install from PyPI
pip install agile-todo-cli

# Add a task and start tracking time
todo add "My first task"
todo start 1

# When done
todo stop
todo done 1

# See all your todos
todo list

# Launch interactive KANBAN board
todo kanban -i

That's it! You're tracking tasks with time. Run todo --help for more.

Features

• ✅ Task Management - Add, edit, delete, and organize tasks
• ⏱️ Time Tracking - Track time spent on tasks with start/stop timers
• 📁 Project Organization - Group tasks into projects with full CRUD operations
• 🔍 Smart Filtering - Filter tasks by project, status, priority, and tags
• 📊 Reports - Daily, weekly, and project-based time reports
• 📤 Export - Export to JSON, CSV, or Markdown
• 🎨 Interactive Mode - Full-featured TUI for task management
• 📋 KANBAN Board - Visual board with vim-style navigation (todo kanban -i)
• 🔄 Cycle Management - Sprint/iteration tracking with check-ins
• 🌳 Subtasks - Hierarchical task relationships with tree view
• ⚙️ Configurable - Customize priorities, date formats, colors, and more
• 🚀 Performance - Optimized database queries with comprehensive indexing
• 🧪 Well-Tested - 90% test coverage with 500+ tests

Installation

# Install from PyPI
pip install agile-todo-cli

# Or install from source
pip install -e .

For existing users: If you have an existing todo database, it will be automatically migrated to the new schema. See MIGRATION_GUIDE.md for details.

Quick Start

Basic Task Management

# Add a task
todo add "Write documentation"

# Add with priority and tags
todo add "Fix bug #123" -p p0 --tags bug urgent

# Add with due date
todo add "Submit report" --due 2025-12-31

# List all active tasks
todo list

# List with filters
todo list --status doing
todo list --project myapp

# Mark as done
todo done 1

Project Management

# Create a project
todo project create "My App" --description "Mobile app development" --color cyan

# List all projects
todo project list

# Show project details and statistics
todo project show "My App"

# Add tasks to a project
todo add "Design login screen" -P "My App"

# Filter tasks by project
todo list --project "My App"

# Archive a project
todo project archive "My App"

# Delete a project (tasks remain unassigned)
todo project delete "My App"

Time Tracking

# Start tracking time on a task
todo start 1

# Check what's currently being tracked
todo active

# Stop tracking
todo stop

# View time spent when marking done
todo done 1

Reports

# Daily report (time spent today)
todo report daily

# Weekly report (time spent this week)
todo report weekly

# Project overview (all projects with stats)
todo report project

# Specific project report
todo report project "My App"

Export

# Export to JSON
todo export json todos.json

# Export to CSV
todo export csv todos.csv

# Export to Markdown
todo export md todos.md

# Export specific project
todo export json myapp.json --project "My App"

Commands

Task Commands

• add - Add a new todo

  todo add "Task description" [-p PRIORITY] [-P PROJECT] [--tags TAG...] [--due DATE]
  

• list - List todos with optional filters

  todo list [--project PROJECT] [--status STATUS] [--all]
  

• show - Show detailed information about a todo

  todo show <id>
  

• done - Mark todo as complete

  todo done <id>
  

• delete - Delete a todo

  todo delete <id> [--force]
  

• edit - Edit a todo's properties

  todo edit <id> [--task TEXT] [--priority PRIORITY] [--project PROJECT] [--tags TAG...]
  

• status - Change todo status (todo/doing/done)

  todo status <id> <status>
  

Project Commands

• project create - Create a new project

  todo project create <name> [--description TEXT] [--color COLOR]
  

• project list - List all projects with statistics

  todo project list [--archived]
  

• project show - Show project details and task breakdown

  todo project show <name>
  

• project edit - Edit project properties

  todo project edit <name> [--name NEW_NAME] [--description TEXT] [--color COLOR]
  

• project archive - Archive a project (hide from active list)

  todo project archive <name>
  

• project unarchive - Restore an archived project

  todo project unarchive <name>
  

• project delete - Delete a project (tasks become unassigned)

  todo project delete <name>
  

Time Tracking Commands

• start - Start time tracking on a task

  todo start <id>
  

• stop - Stop time tracking

  todo stop [<id>]
  

• active - Show currently tracking task

  todo active
  

Reporting & Export

• report - Generate time reports

  todo report daily [--date DATE]
  todo report weekly [--date DATE]
  todo report project [PROJECT_NAME]
  

• export - Export todos to various formats

  todo export <format> [output_file] [--project PROJECT] [--include-done]
  

  Supported formats: json, csv, md/markdown

Other Commands

• stats - Show overall statistics

  todo stats
  

• interactive - Launch interactive mode (TUI)

  todo interactive
  

• config - View or modify configuration

  todo config show
  todo config set <key> <value>
  todo config path
  

• version - Show version information

  todo version
  

Configuration

Customize Todo CLI behavior through the config file (~/.config/todo-cli/config.yaml):

# Default priority for new tasks (p0, p1, p2, p3)
default_priority: p2

# Date format (YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY)
date_format: YYYY-MM-DD

# Time format (24h, 12h)
time_format: 24h

# Color scheme (auto, none)
color_scheme: auto

# Confirm before deleting tasks
confirm_delete: true

# Auto-start timer when adding tasks
auto_start_on_add: false

# Show completed tasks in list by default
show_completed_in_list: false

View and modify configuration:

# Show all configuration
todo config show

# Set a value
todo config set default_priority p1
todo config set confirm_delete false

# Show config file location
todo config path

Interactive Mode

Launch a full-featured terminal UI with todo interactive:

• Menu-driven interface - Navigate with arrow keys
• All commands available - Add, edit, delete, start/stop timers
• Real-time updates - See changes immediately
• Keyboard shortcuts - Fast command execution
• Command aliases - l for list, d for done, etc.

KANBAN Board

Launch the interactive KANBAN board with todo kanban -i or todo kanban --interactive:

┌─────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
│   Backlog   │    Todo     │ In Progress │   Review    │    Done     │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
│ 🔴 #1 Task  │ 🟡 #3 Task  │ 🔵 #5 Task  │             │ ⚪ #7 Task  │
│ 🟡 #2 Task  │ 🔵 #4 Task  │             │             │             │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘

Keyboard Shortcuts

Key	Action
h / ←	Move to previous column
l / →	Move to next column
j / ↓	Select next task
k / ↑	Select previous task
Enter	Move task to next column
m	Move task to specific column
r	Refresh board
d	Toggle done column visibility
?	Show help
q / Esc	Quit

Filtering

# Filter by project
todo kanban -i --project "My App"

# Filter by priority
todo kanban -i --priority p0

# Filter by tags
todo kanban -i --tags urgent bug

# Show done column
todo kanban -i --show-done

CLI View (Non-Interactive)

# View KANBAN board in terminal (static view)
todo kanban

# Move task to column
todo kanban move 1 in-progress

# Show column counts
todo kanban --counts

Cycle Management

Organize work into time-boxed cycles (sprints/iterations):

# Start a new cycle
todo cycle start "Sprint 1" --duration 14

# Check in on a cycle (daily standup)
todo cycle check-in --notes "Completed auth module"

# List all cycles
todo cycle list

# Show current cycle status
todo cycle status

# Complete a cycle
todo cycle complete

# View cycle report
todo cycle report "Sprint 1"

Cycle Workflow

1. Start - Begin a new cycle with a name and duration
2. Check-in - Record daily progress and notes
3. Complete - End the cycle and generate summary
4. Report - Review cycle metrics and task completion

Database & Migrations

Todo CLI uses SQLite for data storage with automatic schema migrations.

Default database location: ~/.local/share/todo-cli/todos.db

Automatic migrations: When you upgrade Todo CLI, your database is automatically migrated to the latest schema version. Backups are created before each migration.

For existing users: See MIGRATION_GUIDE.md for details on upgrading from older versions.

Performance

Todo CLI is designed for speed:

• ✅ List 1000 tasks: <100ms
• ✅ Filter by project: <100ms
• ✅ Project statistics: <200ms
• ✅ Comprehensive database indexing for optimal query performance

See docs/performance.md for detailed benchmarks.

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=todo_cli --cov-report=term-missing

# Run specific test file
pytest tests/test_projects.py

# Run performance benchmarks
pytest tests/test_performance.py

Contributing

See CONTRIBUTING.md for development setup, testing guidelines, and contribution workflow.

Project Structure

todo-cli/
├── todo_cli/           # Main package
│   ├── main.py         # CLI entry point and commands
│   ├── database.py     # Database operations
│   ├── projects.py     # Project management
│   ├── kanban.py       # KANBAN board logic
│   ├── kanban_tui.py   # KANBAN interactive TUI (Textual)
│   ├── cycles.py       # Cycle/sprint management
│   ├── subtasks.py     # Subtask relationships
│   ├── migrations.py   # Database migrations
│   ├── models.py       # Data models
│   ├── config.py       # Configuration management
│   ├── display.py      # Terminal output formatting
│   ├── reports.py      # Report generation
│   ├── export.py       # Export functionality
│   └── interactive.py  # Interactive mode
├── tests/              # Test suite (500+ tests, 90% coverage)
├── docs/               # Documentation
│   ├── architecture.md # System architecture and design
│   └── performance.md  # Performance benchmarks
├── README.md           # This file
├── CONTRIBUTING.md     # Development guide
└── MIGRATION_GUIDE.md  # Migration instructions

Roadmap

Epic 1: Foundation ✅ (Complete)

• ✅ Project management with full CRUD operations
• ✅ Database schema v1 with migrations
• ✅ Smart filtering by project, status, priority
• ✅ Performance optimization and benchmarking
• ✅ Comprehensive test coverage (87%)

Epic 2: Sub-tasks ✅ (Complete)

• ✅ Hierarchical task relationships
• ✅ Tree view for task lists (--tree flag)
• ✅ Parent-child task dependencies
• ✅ Subtask progress tracking

Epic 3: KANBAN Board ✅ (Complete)

• ✅ Visual board view (Backlog/Todo/In Progress/Review/Done)
• ✅ Interactive TUI with vim-style navigation
• ✅ Task movement between columns
• ✅ Filtering by project, priority, tags

Epic 4: Cycles & Sprints ✅ (Complete)

• ✅ Sprint/iteration management
• ✅ Cycle-based task organization
• ✅ Daily check-ins with notes
• ✅ Cycle reports and statistics

Future (Planned)

• Recurring tasks
• Calendar integration
• Cloud sync
• Team collaboration

License

See LICENSE file for details.

Support

• Documentation: See docs/ directory
• Issues: Report bugs or request features via GitHub Issues
• Contributing: See CONTRIBUTING.md

Changelog

v1.1.0 (2025-12-27)

New Features:

• Interactive KANBAN Board - Full TUI with vim-style navigation (todo kanban -i)
  • 5-column workflow: Backlog → Todo → In Progress → Review → Done
  • Keyboard shortcuts: h/j/k/l navigation, Enter to advance, m to move
  • Filter by project, priority, or tags
• Cycle Management - Sprint/iteration tracking
  • Start, check-in, complete, and report on cycles
  • Daily standup notes and progress tracking
• Subtask Support - Hierarchical task relationships
  • Tree view with --tree flag
  • Parent-child task dependencies
  • Subtask progress indicators

Improvements:

• 500+ tests with 90% coverage
• Enhanced KANBAN column management
• Cycle-based task organization

v1.1.0-alpha (Epic 1 Release)

New Features:

• Project management with create, list, show, edit, archive, delete operations
• Project-based task filtering with --project flag
• Database schema v1 with automatic migrations
• Comprehensive performance optimizations (all queries <200ms)
• Project statistics and reporting

Improvements:

• Added 313+ tests with 87% coverage
• Comprehensive database indexing for optimal performance
• Enhanced filtering capabilities (project + status combinations)
• Backward compatibility with legacy project strings

Migration:

• Existing databases automatically migrated to v1 schema
• Legacy project strings converted to project references
• See MIGRATION_GUIDE.md for details

---

Built with ❤️ using Python, Typer, and Rich.