---

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. license: MIT compatibility: Requires Python 3 and pip. Works on macOS, Linux, and Windows. metadata: {"clawdbot":{"requires":{"bins":["topydo"]},"install":[{"id":"brew","kind":"brew","formula":"topydo","bins":["topydo"],"label":"Install topydo (brew)"},{"id":"pip","kind":"pip","package":"topydo","bins":["topydo"],"label":"Install topydo (pip)"}]}}

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

Copy(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)

Copybrew install topydo

pip (all platforms)

Copypip3 install topydo

With optional features:

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

apt (Ubuntu/Debian)

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

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

Copytopydo add "Buy groceries"

With priority (A is highest):

Copytopydo add "(A) Urgent task"

With project and context:

Copytopydo add "Write report +ProjectX @office"

With due date (absolute):

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

With due date (relative):

Copytopydo add "Call mom due:tomorrow"

With due date (weekday):

Copytopydo add "Weekly review due:fri"

With start/threshold date:

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

With recurrence (weekly):

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

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

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

With dependency (must complete before task 1):

Copytopydo add "Write tests before:1"

As subtask of task 1:

Copytopydo add "Review code partof:1"

Listing Tasks

List all relevant tasks:

Copytopydo ls

Include hidden/blocked tasks:

Copytopydo ls -x

Filter by project:

Copytopydo ls +ProjectX

Filter by context:

Copytopydo ls @office

Filter by priority:

Copytopydo ls "(A)"

Filter by priority range:

Copytopydo ls "(>C)"

Filter tasks due today:

Copytopydo ls due:today

Filter overdue tasks:

Copytopydo ls "due:<today"

Filter tasks due by Friday:

Copytopydo ls "due:<=fri"

Combine multiple filters:

Copytopydo ls +ProjectX @office due:today

Exclude context:

Copytopydo ls -- -@waiting

Sort by priority:

Copytopydo ls -s priority

Sort descending by due date, then priority:

Copytopydo ls -s desc:due,priority

Group by project:

Copytopydo ls -g project

Limit to 5 results:

Copytopydo ls -n 5

Custom output format:

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

Output as JSON:

Copytopydo ls -f json

Completing Tasks

Complete task by ID:

Copytopydo do 1

Complete multiple tasks:

Copytopydo do 1 2 3

Complete all tasks due today:

Copytopydo do -e due:today

Complete with custom date:

Copytopydo do -d yesterday 1

Priority Management

Set priority A:

Copytopydo pri 1 A

Set priority for multiple tasks:

Copytopydo pri 1 2 3 B

Remove priority:

Copytopydo depri 1

Tagging Tasks

Set due date:

Copytopydo tag 1 due tomorrow

Star a task:

Copytopydo tag 1 star 1

Remove a tag:

Copytopydo tag 1 due

Set custom tag with relative date:

Copytopydo tag -r 1 review 2w

Modifying Tasks

Append text to task:

Copytopydo append 1 "additional notes"

Append due date:

Copytopydo append 1 due:friday

Edit task in text editor:

Copytopydo edit 1

Edit all tasks in project:

Copytopydo edit -e +ProjectX

Deleting Tasks

Delete by ID:

Copytopydo del 1

Delete multiple:

Copytopydo del 1 2 3

Delete by expression:

Copytopydo del -e completed:today

Dependencies

Add dependency (task 2 depends on task 1):

Copytopydo dep add 2 to 1

Task 2 is part of task 1:

Copytopydo dep add 2 partof 1

List what depends on task 1:

Copytopydo dep ls 1 to

List what task 1 depends on:

Copytopydo dep ls to 1

Remove dependency:

Copytopydo dep rm 2 to 1

Visualize dependencies (requires graphviz):

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

Postponing Tasks

Postpone by 1 week:

Copytopydo postpone 1 1w

Postpone by 3 days:

Copytopydo postpone 1 3d

Postpone including start date:

Copytopydo postpone -s 1 1w

Other Commands

Sort the todo.txt file:

Copytopydo sort

Revert last command:

Copytopydo revert

Show revert history:

Copytopydo revert ls

List all projects:

Copytopydo lsprj

List all contexts:

Copytopydo lscon

Archive completed tasks:

Copytopydo 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