agile-todo-cli 1.1.0

CLI tool for managing daily todos with time tracking

Todo CLI

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

TL;DR

# Install
pip install -e .

# 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

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
• ⚙️ Configurable - Customize priorities, date formats, colors, and more
• 🚀 Performance - Optimized database queries with comprehensive indexing
• 🧪 Well-Tested - 87% test coverage with 313+ tests

Installation

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.

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
│   ├── 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 (313+ tests, 87% 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 (Planned)

• Hierarchical task relationships
• Tree view for task lists
• Parent-child task dependencies
• Nested time tracking

Epic 3: KANBAN Board (Planned)

• Visual board view (Todo/Doing/Done columns)
• Drag-and-drop task movement (TUI)
• Column customization
• Workflow automation

Epic 4: Cycles & Sprints (Planned)

• Sprint/iteration management
• Cycle-based task organization
• Sprint planning and retrospectives
• Burndown charts

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-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.