todo

ultra-light personal CLI task manager

No accounts · No cloud · No background processes · One Python file

Install · Quick start · Commands · Encryption

---

---

Features

Nested tags — #work #backend hierarchies	Priorities — !1 urgent · !2 medium · !3 normal
Due dates — @YYYY-MM-DD, overdue highlighting	Encryption — AES/Fernet with PBKDF2 (opt-in)
Per-user data — each OS user isolated	Interactive TUI — arrow keys on all platforms
Zero deps — works out of the box	Atomic writes — crash-safe file saving

---

Install

Linux / macOS	Windows	Manual
curl -fsSL https://raw.githubusercontent.com/\ luuucciiffeerr/TODO/main/install.sh | bash	irm https://raw.githubusercontent.com/\ luuucciiffeerr/TODO/main/install.ps1 | iex	cp todo.py ~/.local/bin/todo.py echo 'exec python3 ~/.local/bin/todo.py "$@"' \ > ~/.local/bin/todo chmod +x ~/.local/bin/todo
Or clone: git clone https://github.com/luuucciiffeerr/TODO.git && cd todo && bash install.sh

---

Quick start

todo -a buy milk                       # add a task
todo -a #work fix bug !1 @2026-06-15  # tagged + priority + due
todo                                   # view your list
todo -d 1                              # mark task #1 done
todo -r 1                              # remove task #1
todo --all                             # expand all tags
todo -i                                # interactive TUI
todo --help                            # full reference

---

Full command reference

USAGE
  todo                          show tasks (tags collapsed)
  todo --all                    expand everything
  todo #work                    open tag by name
  todo #2                       open tag by number

ADDING
  todo -a fix the bug           add task to root
  todo -a #work fix bug         add to tag (creates if missing)
  todo -a #work #backend bug    nested tag path
  todo -a !1 urgent thing       priority
  todo -a call @2025-05-30      due date
  todo -a #work !1 @2025-05-30  all combined

MODIFYING
  todo -d 3                     toggle done
  todo -e 2 new text            edit task
  todo -m 2 up|down             reorder

REMOVING
  todo -r 3                     remove task
  todo -r #work 2               remove inside tag
  todo --rmtag #work            remove tag + contents

SEARCH & MISC
  todo -s keyword               search across all tags
  todo --clear                  wipe everything (confirms)
  todo --version                print version

ENCRYPTION
  todo --encrypt                encrypt data with password
  todo --decrypt                remove encryption

---

Interactive TUI

Run todo -i for a full-screen interface with arrow-key navigation.

Key	Action	Key	Action
↑ ↓	Navigate	Space	Toggle done
→	Expand tag	d	Delete task/tag
←	Collapse tag	a	Add task
t	New tag	e	Edit / rename
q	Quit

---

Encryption

pip install cryptography
todo --encrypt

Stack	Detail
Algorithm	AES-128-CBC (Fernet)
KDF	PBKDF2-HMAC-SHA256
Iterations	480,000 (NIST 2023)
Salt	32-byte random, per-user
Writes	Atomic (tmp → rename)

Password via TODO_PASSWORD env var avoids shell history.

⚠ No password recovery. Back up your .salt file alongside tasks.json.

---

Data location

OS	Path
Linux	~/.local/share/todo/tasks.json
macOS	~/.local/share/todo/tasks.json
Windows	%APPDATA%\todo\tasks.json

Data directory: chmod 700 on Unix. Each OS user isolated.

---

Requirements

• Python 3.8+ — no other required dependencies
• cryptography package (optional, for --encrypt/--decrypt)

---

made to be used, not configured

MIT License · Security · Changelog · Contributing · Website