Introduction
# Todoist Integration
Manage tasks via `td` CLI (todoist-rs).
## Installation
```bash brew install LuoAndOrder/tap/todoist-cli ```
Or install via Cargo: `cargo install todoist-cli-rs`
## Sync Behavior
- **Writes auto-sync**: `add`, `done`, `edit`, `delete` hit the API directly - **Reads use cache**: `list`, `today`, `show` read from local cache - **Sync when needed**: Use `--sync` flag or `td sync` for fresh data
```bash td sync # Incremental sync (fast) td sync --full # Full rebuild if cache seems off ```
## Common Operations
### List Tasks
```bash # Today's agenda (includes overdue) td today --sync
# Today only (no overdue) td today --no-overdue
# All tasks td list --sync
# By project td list -p "Inbox" --sync td list -p "Work" --sync
# High priority td list -f "p1 | p2" --sync
# By label td list -l "urgent" --sync
# Complex filters td list -f "today & p1" --sync td list -f "(today | overdue) & !@waiting_on" --sync ```
### Add Tasks
Quick add (natural language): ```bash td quick "Buy milk tomorrow @errands #Personal" td quick "Review PR tomorrow" --note "Check the auth changes carefully" ```
Structured add: ```bash td add "Task content" \ -p "Inbox" \ -P 2 \ -d "today" \ -l "urgent"
# With description td add "Prepare quarterly report" -P 1 -d "friday" \ --description "Include sales metrics and customer feedback summary" ```
Options: - `-P, --priority` - 1 (highest) to 4 (lowest, default) - `-p, --project` - project name - `-d, --due` - due date ("today", "tomorrow", "2026-01-30", "next monday") - `-l, --label` - label (repeat for multiple) - `--description` - task description/notes (shown below task title) - `--section` - target section within project - `--parent` - parent task ID (creates subtask)
### Complete Tasks
```bash td done <task-id> td done <id1> <id2> <id3> # Multiple at once td done <id> --all-occurrences # End recurring task permanently ```
### Modify Tasks
```bash td edit <task-id> -c "New content" td edit <task-id> --description "Additional notes here" td edit <task-id> -P 1 td edit <task-id> -d "tomorrow" td edit <task-id> --add-label "urgent" td edit <task-id> --remove-label "next" td edit <task-id> --no-due # Remove due date td edit <task-id> --section "Next Actions" td edit <task-id> -p "Work" # Move to different project ```
Edit options: - `-c, --content` - update task title - `--description` - update task description/notes - `-P, --priority` - change priority (1-4) - `-d, --due` - change due date - `--no-due` - remove due date - `-l, --label` - replace all labels - `--add-label` - add a label - `--remove-label` - remove a label - `-p, --project` - move to different project - `--section` - move to section within project
### Show Task Details
```bash td show <task-id> td show <task-id> --comments ```
### Delete Tasks
```bash td delete <task-id> ```
### Reopen Completed Tasks
```bash td reopen <task-id> ```
## Project & Label Management
```bash # Projects td projects # List all td projects add "New Project" td projects show <id>
# Labels td labels # List all td labels add "urgent" ```
## Filter Syntax
Use with `-f/--filter`: - `|` for OR: `today | overdue` - `&` for AND: `@next & #Personal` - Parentheses: `(today | overdue) & p1` - Negation: `!@waiting_on` - Priority: `p1`, `p2`, `p3`, `p4` - Dates: `today`, `tomorrow`, `overdue`, `no date`, `7 days`
## Workflow Tips
1. **Morning review**: `td today --sync` 2. **Quick capture**: `td quick "thing to do"` 3. **Focus list**: `td list -f "@next" --sync` 4. **Waiting on**: `td list -f "@waiting_on" --sync` 5. **End of day**: `td today` (cache is fine, already synced)