topydo
/topydo
Manages todo.txt tasks using topydo CLI. Adds, lists, completes, prioritizes, tags, and organizes 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.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 06.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Manages todo.txt tasks using topydo CLI. Adds, lists, completes, prioritizes, tags, and organizes 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.
Original author description
Manages todo.txt tasks using topydo CLI. Adds, lists, completes, prioritizes, tags, and organizes 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.
How it works
- Task Format Reference
- Installation
- Configuration
- Adding Tasks
- Listing Tasks
- Completing Tasks
- Priority Management
- Tagging Tasks
- Modifying Tasks
- Deleting Tasks
SKILL.md preview
---
name: topydo
description: Manages todo.txt tasks using topydo CLI. Adds, lists, completes, prioritizes, tags, and organizes 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)
```bash
brew install topydo
```
### pip (all platforms)
```bash
pip3 install topydo
```
With optional features:
```bash
pip3 install 'topydo[columns,prompt,ical]'
```
### Linux (pipx preferred)
```bash
pipx install topydo
```
If `pipx` is unavailable, install it with your system package manager first, or use a Python virtual environment.
## Configuration
Config file locations are loaded in this order; later files override earlier
values:
- `/etc/topydo.conf`
- `~/.config/topydo/config`
- `~/.topydo`
- `.topydo` (current directory)
- `topydo.conf` (current directory)
- `topydo.ini` (current directory)
- A configuration file passed with `-c`
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
Versions
The database has no other skills named topydo.
Database snapshot: 13.11.2026 · package version 1de646d44eb0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96todo
Use when the user invokes /todo, says "add to tasks", or asks to add or update an item in this project's TODOS.md task list. - 100microsoft-todo
Read and manage Microsoft To Do task lists and tasks via Microsoft Graph v1.0. Use when the user mentions Microsoft To Do, their Outlook tasks, todo / pending items, due dates or reminders, adding or completing a task, or organising task lists. - 100tasks
Work with markdown-based task lists in .llm/todo.md files. Use when managing tasks, working with todo lists, extracting incomplete tasks, marking tasks complete, or implementing tasks from a task list. - 95google-tasks
Read and manage Google Tasks task lists and individual tasks via the Tasks v1 REST API. Use when the user mentions Google Tasks, todo / pending / overdue tasks, weekly task recap, grouping todos by list, adding or completing a task, or moving / deleting tasks. - 100todo
Add, complete, view, or link plans to items in the project backlog (GitHub issues or brain/todos.md). Use when the user says "todo", "add a todo", "mark done", "what's on the backlog", "show todos", "list tasks", "check off", or wants to manage their task list. - 90todo-add
Use when a message contains `TODO ADD: <requirement>`. Not for deepening coarse lists: use todos-enhance. Not for resyncing lists: use todos-update. Not for retitling/reordering/completing todos.