@walknpm/todo-cli

todo-cli

English | 简体中文

A zero-dependency Node.js todo list manager with CLI + Web UI. Full CRUD, subtasks, recurring tasks, dependencies, time tracking, pinning, bulk operations, categories/tags, priority sorting, due dates, search, statistics, kanban board, calendar view, timeline, export (JSON / CSV / Markdown), and auto-update. Data persists to ~/.todo-cli/todos.json.

Requirements

• Node.js >= 18

Quick install

Via npm:

npm install -g @walknpm/todo-cli
todo --version   # → todo v2.0.0

Via git:

git clone https://gitcode.com/hw_aishell_projects/todo_cli.git
cd todo_cli
npm install -g .
todo --version   # → todo v2.0.0

🚀 Web UI

Start the web server with:

todo web              # default port 3456
todo web 8080         # custom port
npm run web           # via npm script

Then open http://localhost:3456 in your browser.

Web UI Features

Feature	Description
Dashboard	Stats cards, completion rate, recent todos, upcoming deadlines
List View	Full todo list with inline actions, filtering, sorting, search
Kanban Board	Drag-and-drop between Pending and Done columns
Calendar	Monthly calendar with todos mapped to due dates
Timeline	Chronological activity feed of all todos
Add/Edit Modal	Full form with all fields including recurrence and pinning
Detail View	Subtask management, dependencies, timestamps, quick actions
Time Tracking	Start/stop timers with floating timer widget
Dark/Light Theme	Toggle with persistence via localStorage
Responsive	Works on desktop, tablet, and mobile
Keyboard Shortcuts	n = new todo, / = search, Esc = close modal

Commands

Core Commands

Command	Description
add <title>	Add a new todo
list	List todos (default command)
show <id>	Show detailed info for a todo
done <id>	Mark a todo as done (done --all = complete all)
toggle <id>	Toggle done / pending
edit <id>	Edit a todo
delete <id>	Delete a todo (alias: rm, remove)
duplicate <id>	Clone a todo (alias: dup)
pin <id>	Toggle pin status
search <keyword>	Search title / tags / category / note / assignee
stats	Show summary statistics
export [json|csv|md]	Export all todos to stdout
archive	Remove all completed todos
clear	Remove ALL todos
web [port]	Start the web UI server (default: 3456)
update	Update todo-cli to latest (--check = check only)
help	Show help

Subtasks

todo subtask add <id> <title>        # Add a subtask
todo subtask done <id> <sid>         # Toggle subtask done
todo subtask edit <id> <sid> <title> # Edit subtask title
todo subtask delete <id> <sid>       # Delete a subtask

Recurring Tasks

todo recur <id> daily   [interval]   # Repeat every N days
todo recur <id> weekly  [interval]   # Repeat every N weeks
todo recur <id> monthly [interval]   # Repeat every N months
todo recur <id> yearly  [interval]   # Repeat every N years
todo recur <id> off                  # Remove recurrence

When a recurring todo is completed, a new pending instance is automatically created with the due date advanced by the recurrence interval.

Dependencies

todo dep add <id> <depId>     # Add dependency (blocks completion)
todo dep remove <id> <depId>  # Remove dependency

Time Tracking

todo timer start <id>         # Start timer (stops any other running timer)
todo timer stop <id>          # Stop timer and log elapsed time
todo timer log <id> <minutes> # Manually log time
todo timer                    # Show active timer

Bulk Operations

todo bulk done <ids...>              # Complete multiple todos
todo bulk delete <ids...>            # Delete multiple todos
todo bulk priority <ids...> -p <val> # Set priority on multiple todos
todo bulk category <ids...> -c <val> # Set category on multiple todos
todo bulk assign <ids...> --assignee <val>  # Set assignee on multiple todos

Flags

Flag	Applies to	Description
-p, --priority <v>	add, edit	high | medium | low (default: medium)
-t, --tags <v>	add, edit	Comma-separated tags
-c, --category <v>	add, edit	Category name
-d, --due <v>	add, edit	Due date YYYY-MM-DD
--note <v>	add, edit	Longer note / description
--title <v>	edit	New title
--assignee <v>	add, edit	Assign to a person
--estimate <v>	add, edit	Estimated minutes to complete
--color <v>	add, edit	Custom color label
--status <v>	list	all | done | pending
--tag <v>	list	Filter by tag
--sort <v>	list	priority | created | due | id | title | updated | order
--pinned	add	Pin the new todo
--overdue	list	Show only overdue items
--due-today	list	Show only items due today
--all	done	Complete all pending
--check	update	Check for update without installing
--format <v>	export	json | csv | md (default: json)

Examples

# Add with all fields
todo add "Submit tax return" -p high -d 2025-01-31 -c finance -t urgent,monthly --note "Include receipts" --estimate 120 --assignee bob

# List & filter
todo list --status pending --sort due
todo list --overdue
todo list --category work --priority high

# Subtasks
todo subtask add 1 "Research options"
todo subtask add 1 "Write draft"
todo subtask done 1 1

# Recurring
todo recur 3 weekly 1
todo done 3   # creates a new instance for next week

# Dependencies
todo dep add 5 3   # todo #5 is blocked until #3 is done

# Time tracking
todo timer start 2
todo timer stop 2
todo timer log 2 30

# Pin & duplicate
todo pin 1
todo duplicate 3

# Bulk operations
todo bulk done 1 2 3
todo bulk priority 1 2 3 -p high

# Web UI
todo web 8080

# Statistics
todo stats

# Export
todo export csv > todos.csv
todo export md

# Auto-update
todo update --check
todo update

Project structure

todo_cli/
├── bin/
│   └── todo.js            # executable entry point (shebang)
├── src/
│   ├── store.js           # JSON file persistence layer
│   ├── todo.js            # domain logic (CRUD, subtasks, recurring, deps, timer, bulk, ...)
│   ├── cli.js             # command parsing, ANSI colours, table output
│   └── server.js          # zero-dependency HTTP server (REST API + static files)
├── web/
│   ├── index.html         # SPA shell
│   ├── css/
│   │   └── style.css      # modern responsive design (dark/light themes)
│   └── js/
│       └── app.js         # SPA application logic (dashboard, list, kanban, calendar, timeline)
├── skill/
│   ├── SKILL.md           # DSH skill instructions
│   ├── README.md          # skill documentation
│   └── CHANGELOG.md       # skill changelog
├── package.json
├── README.md              # English documentation
└── README.zh-CN.md        # Chinese documentation

REST API

The web server exposes a REST API at /api/:

Method	Endpoint	Description
GET	/api/todos	List all todos (supports query filters)
POST	/api/todos	Create a new todo
GET	/api/todos/:id	Get a single todo
PATCH	/api/todos/:id	Edit a todo
DELETE	/api/todos/:id	Delete a todo
POST	/api/todos/:id/toggle	Toggle done status
POST	/api/todos/:id/complete	Mark as done
POST	/api/todos/:id/pin	Toggle pin
POST	/api/todos/:id/duplicate	Duplicate a todo
POST	/api/todos/:id/reorder	Reorder a todo
POST	/api/todos/:id/subtasks	Add a subtask
POST	/api/todos/:id/subtasks/:sid/toggle	Toggle subtask
PATCH	/api/todos/:id/subtasks/:sid	Edit subtask
DELETE	/api/todos/:id/subtasks/:sid	Delete subtask
POST	/api/todos/:id/recurring	Set/remove recurrence
POST	/api/todos/:id/dependencies	Add dependency
DELETE	/api/todos/:id/dependencies/:depId	Remove dependency
POST	/api/todos/:id/timer/start	Start timer
POST	/api/todos/:id/timer/stop	Stop timer
POST	/api/todos/:id/timer/log	Log time manually
GET	/api/stats	Get statistics
GET	/api/search?q=<keyword>	Search todos
GET	/api/timer	Get active timer
POST	/api/bulk	Bulk operations
POST	/api/complete-all	Complete all pending
POST	/api/archive	Archive completed
POST	/api/clear	Clear all
GET	/api/export?format=<fmt>	Export todos

License

MIT