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]' ```

### apt (Ubuntu/Debian) ```bash 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`: ```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