topydo

name	topydo
description	Manage todo.txt tasks using topydo CLI. Add, list, complete, prioritize, tag, and organize tasks with dependencies, due dates, recurrence, and projects. Use for any task management, todo lists, or when the user mentions tasks, todos, or todo.txt. Requires Python 3 and pip. Works on macOS, Linux, and Windows.
license	MIT
metadata	{"author":"github.com/bastos","version":"2.0"}

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