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)

brew install topydo

pip (all platforms)

pip3 install topydo

With optional features:

pip3 install 'topydo[columns,prompt,ical]'

apt (Ubuntu/Debian)

sudo apt install python3-pip && pip3 install topydo

Configuration

Config file locations (in order of precedence):

• topydo.conf or .topydo (current directory)
• ~/.topydo or ~/.config/topydo/config
• /etc/topydo.conf

Example ~/.topydo:

[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:

topydo add "Buy groceries"

With priority (A is highest):

topydo add "(A) Urgent task"

With project and context:

topydo add "Write report +ProjectX @office"

With due date (absolute):

topydo add "Submit proposal due:2025-01-15"

With due date (relative):

topydo add "Call mom due:tomorrow"

With due date (weekday):

topydo add "Weekly review due:fri"

With start/threshold date:

topydo add "Future task t:2025-02-01"

With recurrence (weekly):

topydo add "Water plants due:sat rec:1w"

With strict recurrence (always on 1st of month):

topydo add "Pay rent due:2025-02-01 rec:+1m"

With dependency (must complete before task 1):

topydo add "Write tests before:1"

As subtask of task 1:

topydo add "Review code partof:1"

Listing Tasks

List all relevant tasks:

topydo ls

Include hidden/blocked tasks:

topydo ls -x

Filter by project:

topydo ls +ProjectX

Filter by context:

topydo ls @office

Filter by priority:

topydo ls "(A)"

Filter by priority range:

topydo ls "(>C)"

Filter tasks due today:

topydo ls due:today

Filter overdue tasks:

topydo ls "due:<today"

Filter tasks due by Friday:

topydo ls "due:<=fri"

Combine multiple filters:

topydo ls +ProjectX @office due:today

Exclude context:

topydo ls -- -@waiting

Sort by priority:

topydo ls -s priority

Sort descending by due date, then priority:

topydo ls -s desc:due,priority

Group by project:

topydo ls -g project

Limit to 5 results:

topydo ls -n 5

Custom output format:

topydo ls -F "%I %p %s %{due:}d"

Output as JSON:

topydo ls -f json

Completing Tasks

Complete task by ID:

topydo do 1

Complete multiple tasks:

topydo do 1 2 3

Complete all tasks due today:

topydo do -e due:today

Complete with custom date:

topydo do -d yesterday 1

Priority Management

Set priority A:

topydo pri 1 A

Set priority for multiple tasks:

topydo pri 1 2 3 B

Remove priority:

topydo depri 1

Tagging Tasks

Set due date:

topydo tag 1 due tomorrow

Star a task:

topydo tag 1 star 1

Remove a tag:

topydo tag 1 due

Set custom tag with relative date:

topydo tag -r 1 review 2w

Modifying Tasks

Append text to task:

topydo append 1 "additional notes"

Append due date:

topydo append 1 due:friday

Edit task in text editor:

topydo edit 1

Edit all tasks in project:

topydo edit -e +ProjectX

Deleting Tasks

Delete by ID:

topydo del 1

Delete multiple:

topydo del 1 2 3

Delete by expression:

topydo del -e completed:today

Dependencies

Add dependency (task 2 depends on task 1):

topydo dep add 2 to 1

Task 2 is part of task 1:

topydo dep add 2 partof 1

List what depends on task 1:

topydo dep ls 1 to

List what task 1 depends on:

topydo dep ls to 1

Remove dependency:

topydo dep rm 2 to 1

Visualize dependencies (requires graphviz):

topydo dep dot 1 | dot -Tpng -o deps.png

Postponing Tasks

Postpone by 1 week:

topydo postpone 1 1w

Postpone by 3 days:

topydo postpone 1 3d

Postpone including start date:

topydo postpone -s 1 1w

Other Commands

Sort the todo.txt file:

topydo sort

Revert last command:

topydo revert

Show revert history:

topydo revert ls

List all projects:

topydo lsprj

List all contexts:

topydo lscon

Archive completed tasks:

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