topydo

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