topydo

# topydo - Todo.txt Task Manager topydo is a powerful CLI for managing tasks in the todo.txt format. It supports dependencies, due dates, start dates, recurrence, priorities, projects, and contexts. ## Task Format Reference ``` (A) 2025-01-11 Task text +Project @Context due:2025-01-15 t:2025-01-10 rec:1w star:1 │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─ Star marker │ │ │ │ │ │ │ └─ Recurrence │ │ │ │ │ │ └─ Start/threshold date │ │ │ │ │ └─ Due date │ │ │ │ └─ Context │ │ │ └─ Project │ │ └─ Task description │ └─ Creation date └─ Priority (A-Z) ``` ## Installation ### Homebrew (macOS, preferred) ```bash brew install topydo ``` ### pip (all platforms) ```bash pip3 install topydo ``` With optional features: ```bash pip3 install 'topydo[columns,prompt,ical]' ``` ### Linux (pipx preferred) ```bash pipx install topydo ``` If `pipx` is unavailable, install it with your system package manager first, or use a Python virtual environment. ## Configuration Config file locations are loaded in this order; later files override earlier values: - `/etc/topydo.conf` - `~/.config/topydo/config` - `~/.topydo` - `.topydo` (current directory) - `topydo.conf` (current directory) - `topydo.ini` (current directory) - A configuration file passed with `-c` Example `~/.topydo`: ```ini [topydo] filename = ~/todo.txt archive_filename = ~/done.txt colors = 1 identifiers = text [add] auto_creation_date = 1 [sort] sort_string = desc:importance,due,desc:priority ignore_weekends = 1 ``` ## Adding Tasks Basic task: ```bash topydo add "Buy groceries" ``` With priority (A is highest): ```bash topydo add "(A) Urgent task" ``` With project and context: ```bash topydo add "Write report +ProjectX @office" ``` With due date (absolute): ```bash topydo add "Submit proposal due:2025-01-15" ``` With due date (relative): ```bash topydo add "Call mom due:tomorrow" ``` With due date (weekday): ```bash topydo add "Weekly review due:fri" ``` With start/threshold date: ```bash topydo add "Future task t:2025-02-01" ``` With recurrence (weekly): ```bash topydo add "Water plants due:sat rec:1w" ``` With strict recurrence (always on 1st of month): ```bash topydo add "Pay rent due:2025-02-01 rec:+1m" ``` With dependency (must complete before task 1): ```bash topydo add "Write tests before:1" ``` As subtask of task 1: ```bash topydo add "Review code partof:1" ``` ## Listing Tasks List all relevant tasks: ```bash topydo ls ``` Include hidden/blocked tasks: ```bash topydo ls -x ``` Filter by project: ```bash topydo ls +ProjectX ``` Filter by context: ```bash topydo ls @office ``` Filter by priority: ```bash topydo ls "(A)" ``` Filter by priority range: ```bash topydo ls "(>C)" ``` Filter tasks due today: ```bash topydo ls due:today ``` Filter overdue tasks: ```bash topydo ls "due:<today" ``` Filter tasks due by Friday: ```bash topydo ls "due:<=fri" ``` Combine multiple filters: ```bash topydo ls +ProjectX @office due:today ``` Exclude context: ```bash topydo ls -- -@waiting ``` Sort by priority: ```bash topydo ls -s priority ``` Sort descending by due date, then priority: ```bash topydo ls -s desc:due,priority ``` Group by project: ```bash topydo ls -g project ``` Limit to 5 results: ```bash topydo ls -n 5 ``` Custom output format: ```bash topydo ls -F "%I %p %s %{due:}d" ``` Output as JSON: ```bash topydo ls -f json ``` ## Completing Tasks Complete task by ID: ```bash topydo do 1 ``` Complete multiple tasks: ```bash topydo do 1 2 3 ``` Complete all tasks due today: ```bash topydo do -e due:today ``` Complete with custom date: ```bash topydo do -d yesterday 1 ``` ## Priority Management Set priority A: ```bash topydo pri 1 A ``` Set priority for multiple tasks: ```bash topydo pri 1 2 3 B ``` Remove priority: ```bash topydo depri 1 ``` ## Tagging Tasks Set due date: ```bash topydo tag 1 due tomorrow ``` Star a task: ```bash topydo tag 1 star 1 ``` Remove a tag: ```bash topydo tag 1 due ``` Set custom tag with relative date: ```bash topydo tag -r 1 review 2w ``` ## Modifying Tasks Append text to task: ```bash topydo append 1 "additional notes" ``` Append due date: ```bash topydo append 1 due:friday ``` Edit task in text editor: ```bash topydo edit 1 ``` Edit all tasks in project: ```bash topydo edit -e +ProjectX ``` ## Deleting Tasks Delete by ID: ```bash topydo del 1 ``` Delete multiple: ```bash topydo del 1 2 3 ``` Delete by expression: ```bash topydo del -e completed:today ``` ## Dependencies Add dependency (task 2 depends on task 1): ```bash topydo dep add 2 to 1 ``` Task 2 is part of task 1: ```bash topydo dep add 2 partof 1 ``` List what depends on task 1: ```bash topydo dep ls 1 to ``` List what task 1 depends on: ```bash topydo dep ls to 1 ``` Remove dependency: ```bash topydo dep rm 2 to 1 ``` Visualize dependencies (requires graphviz): ```bash topydo dep dot 1 | dot -Tpng -o deps.png ``` ## Postponing Tasks Postpone by 1 week: ```bash topydo postpone 1 1w ``` Postpone by 3 days: ```bash topydo postpone 1 3d ``` Postpone including start date: ```bash topydo postpone -s 1 1w ``` ## Other Commands Sort the todo.txt file: ```bash topydo sort ``` Revert last command: ```bash topydo revert ``` Show revert history: ```bash topydo revert ls ``` List all projects: ```bash topydo lsprj ``` List all contexts: ```bash topydo lscon ``` Archive completed tasks: ```bash topydo archive ``` ## Relative Dates - `today`, `tomorrow`, `yesterday` - Weekdays: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` - Periods: `1d` (days), `2w` (weeks), `3m` (months), `1y` (years) - Business days: `5b` (excludes weekends) ## Sort/Group Fields - `priority`, `due`, `creation`, `completed` - `importance`, `importance-avg` - `project`, `context`, `text`, `length` Prefix with `desc:` for descending. Example: `desc:importance,due` ## Tips - Use a clean, human-readable format to present results to the user - Enable stable text IDs: set `identifiers = text` in config - Star important tasks: add `star:1` tag - Hidden tags by default: `id`, `p`, `ical` - Importance = priority + due date proximity + star status