🚀 ZODO - Ultimate Todo CLI

A production-ready command-line task manager with 33 commands. Features Kanban workflows, time tracking, desktop notifications, analytics, and team collaboration tools.

✨ Key Features

✅ 33 Powerful Commands - Complete task lifecycle management
📊 Kanban Board - Visual todo/doing/done workflow
🎯 Smart Filtering - By priority, status, category, search
📅 Deadline Management - Track dates, alerts, analytics
📈 Time Tracking - Estimate vs actual, accuracy scores
🔔 Desktop Notifications - Real-time deadline alerts
📝 Notes & Comments - Timestamped task history
👥 Team Features - Assignees, bulk operations, workload view
💾 Data Management - Import/export JSON/CSV, archive system
🎨 Rich UI - Color-coded, progress bars, boxed displays

📦 Installation

# Global install
npm install -g zodo

# Local development
npm install
npm link

🎯 Quick Start

# Create & manage tasks
zodo add "Buy groceries" -p HIGH -c Shopping -d 2025-12-25
zodo board              # View Kanban board
zodo done abc1 -t 2     # Mark complete + log 2 hours

# Check deadlines
zodo today              # Today's tasks
zodo notify -n          # Desktop notifications
zodo overdue            # What's late?

# Get insights
zodo stats              # Analytics
zodo workload           # Capacity by category
zodo estimate           # Time accuracy

📚 Complete Command Reference (33 Commands)

🔧 Task Management (Core)

add - Create a new task

zodo add "Task title"
zodo add "Buy groceries" -p HIGH -c Shopping -d 2025-12-25 -e 2 -D "Store list"

Options: -p priority, -c category, -d due date, -e estimate hours, -D description

edit - Modify task properties

zodo edit abc1 -t "New title"
zodo edit abc1 -p HIGH -d 2025-12-25 -s doing

Options: -t title, -p priority, -c category, -d due, -s status, -e estimate, -D description

delete - Remove a task

zodo delete abc1 --force

Options: -f, --force skip confirmation

view - Show full task details

zodo view abc1

Displays: All task info - status, priority, category, description, dates, times, assignee, ID

move - Change task status

zodo move abc1 todo        # Move to TODO
zodo move abc1 doing       # Move to DOING
zodo move abc1 done        # Move to DONE

done - Quick completion with time logging

zodo done abc1             # Mark complete
zodo done abc1 -t 2.5      # Mark complete + log 2.5 hours

duplicate - Clone a task

zodo duplicate abc1  # Creates "(copy)" variant with fresh ID

list - Display all tasks

zodo list           # Simple list
zodo list --table   # Formatted table view

📅 Deadline & Time Management (6 commands)

deadline - View all tasks with due dates

zodo deadline              # Sort by date
zodo deadline --sort overdue  # Overdue first

today - Today's dashboard

zodo today  # Show tasks due today + in-progress tasks

upcoming - Future deadlines

zodo upcoming              # Next 7 days
zodo upcoming -d 30        # Next 30 days

overdue - Crisis view

zodo overdue  # List all past-due tasks with urgency

track - Log time spent

zodo track abc1 2          # Set actual hours to 2h
zodo track abc1 1.5 --add  # Add 1.5h to existing total

estimate - Time tracking analytics

zodo estimate              # Show accuracy metrics
zodo estimate -c "Work"   # For specific category

Shows: Estimated vs actual, variance %, accuracy score

notify - Deadline alerts

zodo notify              # Check 24-hour window
zodo notify -h 48        # Check 48-hour window
zodo notify -n           # Send desktop notifications
zodo notify --desktop --hours 7  # Weekly check with popup

🔍 Search & Filter (4 commands)

search - Find tasks by keyword

zodo search "keyword"           # Search everywhere
zodo search "meeting" --type title  # Search titles only
zodo search "urgent" --type desc    # Search descriptions only

filter - Advanced multi-criteria filtering

zodo filter -s doing              # By status
zodo filter -p HIGH -c Work       # By priority + category
zodo filter --category Personal   # By category

sort - Organize by field

zodo sort --by priority      # HIGH → MEDIUM → LOW
zodo sort --by due           # By due date
zodo sort --by status        # By workflow state
zodo sort --by created       # By creation date
zodo sort --by priority -r   # Reverse order

priority - Quick level filters

zodo priority high     # Show all HIGH priority
zodo priority medium   # Show all MEDIUM priority
zodo priority low      # Show all LOW priority

📊 Analytics & Views (5 commands)

stats - Overall statistics dashboard

zodo stats

Shows: Total count, by-status breakdown, by-priority breakdown, completion %, overdue count, time totals

board - Kanban board

zodo board       # Visual TODO | DOING | DONE columns
zodo board -c    # Compact mode

workload - Capacity by category

zodo workload

Shows: Tasks grouped by category with progress bars, time estimates

backlog - Unscheduled tasks

zodo backlog  # Show all TODO items without due dates

tags - Category overview

zodo tags  # List all categories with active & done counts

💾 Archive & Bulk (4 commands)

archive - Move to archive

zodo archive abc1

restore - Recover from archive

zodo restore abc1

bulk - Batch operations

zodo bulk archive -p HIGH --force           # Archive high priority
zodo bulk delete -c Done --force            # Delete by category
zodo bulk delete -s doing --force           # Delete by status

Actions: archive, delete (filter + --force required)

clear - Clear tasks

zodo clear           # Remove completed tasks
zodo clear --all --force  # Delete everything (dangerous!)

📤 Data Management (3 commands)

export - Export tasks

zodo export                    # Export to export.json
zodo export -f csv -o tasks.csv  # CSV format
zodo export -f json -o backup.json  # JSON backup

import - Import tasks

zodo import tasks.json

Auto-generates new IDs and timestamps

👥 Collaboration (2 commands)

assign - Assign to team member

zodo assign abc1 "john"
zodo assign abc1 "sarah@company.com"

notes - Add task comments

zodo notes abc1 --add "Client feedback needed"
zodo notes abc1 --list  # View all notes with timestamps

📚 Commands

🎨 Visual Indicators

Priority Symbols & Colors

Level	Symbol	Color
HIGH	🔴	Red
MEDIUM	🟡	Yellow
LOW	🟢	Cyan

Status Colors

Status	Color
TODO	Yellow
DOING	Blue
DONE	Green

Alerts & Indicators

⚠️ OVERDUE - Past deadline
🚨 CRITICAL - Multiple overdue
⏰ IMMINENT - Due within 24 hours

💾 Data Storage

zodo/
├── data/
│   ├── db.json        # Active tasks
│   └── archive.json   # Archived tasks
├── bin/
│   └── index.js       # Main CLI
├── package.json
└── README.md

Task Structure

{
  "id": "uuid",
  "title": "Task name",
  "description": "Details",
  "status": "todo|doing|done",
  "priority": "HIGH|MEDIUM|LOW",
  "category": "Work",
  "dueDate": 1735689600000,
  "estimatedHours": 2,
  "actualHours": 1.5,
  "notes": [{"text": "...", "created": "..."}],
  "assignee": "john",
  "createdAt": 1735603200000,
  "updatedAt": 1735603200000
}

🚀 Practical Workflows

Daily Standup (5 min)

zodo today          # What's due today?
zodo board          # Workflow overview
zodo notify -n      # Any urgent alerts?

Weekly Planning (15 min)

zodo upcoming -d 7        # Next week tasks
zodo backlog              # Unscheduled work
zodo estimate            # Time analysis
zodo stats               # Overall progress

Sprint Retrospective (30 min)

zodo stats              # Completion %, velocities
zodo estimate           # Estimation accuracy
zodo workload           # Team capacity used
zodo overdue            # What slipped?

Create New Sprint

# Create sprint tasks
zodo add "Design" -p HIGH -c Frontend -d 2025-12-20 -e 8
zodo add "API" -p HIGH -c Backend -d 2025-12-22 -e 16
zodo add "Testing" -p MEDIUM -c QA -d 2025-12-24 -e 12

# View board
zodo board
zodo stats

Track Progress

zodo move abc1 doing            # Start task
zodo track abc1 2 --add         # Log 2 hours
zodo notes abc1 --add "70% done"
zodo done abc1 -t 2.5           # Complete + log final hours

Find Bottlenecks

zodo filter -s doing       # What's stuck in progress?
zodo estimate              # Estimation accuracy
zodo workload              # By category capacity
zodo overdue               # What's late?

Project Handoff

zodo export -f csv -o project.csv  # Export for handoff
zodo assign abc1 "jane"             # Reassign tasks
zodo workload                       # Show capacity

Bulk Cleanup

zodo bulk archive -s done --force   # Archive completed
zodo clear --force                  # Remove old done tasks
zodo bulk delete -p LOW --force     # Remove low priority

Export for Reporting

zodo export -f csv -o tasks.csv
zodo stats  # Screenshot for dashboard
# Import into Excel/Sheets for reporting

🛠️ Advanced Usage

Combine Multiple Commands

# Chain for workflow
zodo done abc1 -t 2 && zodo move xyz2 doing && zodo notify -n

# Find and process
zodo search "urgent" | grep todo

Cron Integration

# Daily reminder (8am every day)
0 8 * * * /usr/local/bin/zodo notify -n

# Weekly report (Friday 5pm)
0 17 * * 5 /usr/local/bin/zodo stats > ~/zodo-weekly.txt

# Archive old completed (monthly)
0 0 1 * * /usr/local/bin/zodo clear --force

Backup Strategy

# Daily JSON backup
zodo export -f json -o ~/backups/zodo-$(date +\%Y-\%m-\%d).json

# Weekly CSV export for analysis
0 0 * * 0 zodo export -f csv -o ~/reports/tasks-$(date +\%Y-W\%V).csv

Team Workflows

# Assign sprint tasks
zodo assign abc1 "alice"
zodo assign abc2 "bob"

# View team workload
zodo workload

# Export for team report
zodo export -f csv -o sprint-status.csv

📝 Pro Tips

Use 4-char ID shortcuts - zodo view abc1 instead of full UUID
Set categories early - Improves filtering, workload analysis, and reporting
Log time frequently - Better estimates over time with --add flag
Review stats weekly - Track velocity and estimation accuracy
Archive regularly - Keeps main DB clean and responsive
Use desktop notifications - Schedule with cron jobs
Export before big changes - Easy backup & restore
Filter before bulk ops - Use --force carefully with bulk commands

🛠️ Troubleshooting

Database corrupted?

# Auto-creates fresh db.json if missing
zodo list

Lost tasks?

# Check archive
zodo tags          # See what categories exist
zodo restore abc1  # Restore from archive

Wrong estimates?

# Analyze accuracy
zodo estimate   # Shows variance % and accuracy score

Too many tasks?

# Use filtering to focus
zodo today          # Today only
zodo priority high  # High priority
zodo filter -s doing  # In progress

Performance slow?

# Archive old completed tasks
zodo bulk archive -s done --force
zodo clear --force

📦 Compatibility

Node.js 14+
OS - Linux, macOS, Windows (WSL)
Shell - bash, zsh, fish
Desktop Notifications - Linux (notify-send), macOS (osascript), Windows (WSL)

📊 Command Categories

Category	Count	Commands
Core CRUD	7	add, edit, delete, view, move, done, duplicate
Time Mgmt	7	deadline, today, upcoming, overdue, track, estimate, notify
Search/Filter	4	search, filter, sort, priority
Analytics	5	stats, board, workload, backlog, tags
Archive/Bulk	4	archive, restore, bulk, clear
Data	3	export, import, list
Collab	2	assign, notes
TOTAL	33	Full suite

🚀 Getting Started

Step 1: Create Your First Task

zodo add "Learn ZODO" -p MEDIUM -e 1

Step 2: View Tasks

zodo list        # Simple list
zodo board       # Kanban board
zodo today       # Today's view

Step 3: Manage Workflow

zodo move [id] doing    # Start working
zodo track [id] 0.5     # Log time
zodo done [id] -t 1     # Complete

Step 4: Explore Features

zodo notify        # Check deadlines
zodo stats         # See progress
zodo search "learn"  # Find tasks

Step 5: Advanced Usage

zodo workload           # Team capacity
zodo estimate          # Time accuracy
zodo export -f csv     # Export report

🎉 Features at a Glance

✅ Full task lifecycle (add → doing → done → archive) ✅ Flexible filtering (by priority, status, category, search) ✅ Kanban board visualization ✅ Time estimation & tracking ✅ Deadline management & alerts ✅ Desktop notifications ✅ Team assignments ✅ Timestamped notes & comments ✅ Analytics & reporting ✅ Bulk operations ✅ Data import/export ✅ Archive/restore system ✅ Color-coded UI ✅ Progress bars & indicators

📄 License

ISC

🤝 Contributing

Contributions welcome! Submit issues and pull requests on GitHub.

📝 Changelog

v3.0 - Complete rewrite

✨ 33 commands (was 10)
✨ Desktop notifications
✨ Team collaboration features
✨ Advanced analytics
✨ Time tracking improvements
✨ Notes & comments
✨ Bulk operations

v2.0 - Kanban workflow

Kanban board view
Multiple statuses
Categories & tags

v1.0 - Simple list

Basic CRUD
Simple list view

🚀 Quick Commands Cheat Sheet

# Most common
zodo add "task" -p HIGH -d 2025-12-25
zodo board
zodo today
zodo done abc1 -t 2

# Management
zodo list
zodo move abc1 doing
zodo edit abc1 -p HIGH

# Insight
zodo stats
zodo notify -n
zodo workload

# Data
zodo export -f csv
zodo import tasks.json

Happy tasking! 🎯

ZODO - The ultimate CLI for task management

Name		Name	Last commit message	Last commit date
bin		bin
data		data
node_modules		node_modules
.gitignore		.gitignore
README.md		README.md
export.json		export.json
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation