tdo Quick Reference (v0.9.0)
Model: Area → Project → Task | Storage: ~/.local/share/tdo/store.json
View
tdo view today|inbox|upcoming|someday|logbook|trash|all|recurring|deadlines
tdo view area "name" # projects + tasks in area
tdo view project "name" # tasks in project
tdo view tag "name" # tasks with tag
tdo view task <id> # full detail of one task
tdo view ... --json # machine-readable output
tdo view ... --csv # CSV output
tdo view ... --watch # live-reload
tdo view ... --all # include completed tasksOldtdo today,tdo inboxetc. still work but are deprecated — usetdo view <sub>.tdo showis an alias fortdo view(same commands, kept for compatibility).
Add / Move
tdo add "Title" [SCHEDULE] [OPTIONS]
tdo move <id> [SCHEDULE] [OPTIONS] # update any field; can take multiple IDsSCHEDULE (mutually exclusive): --today --tomorrow --next-week --someday --on DATE
OPTIONS: --due DATE -p PROJECT -a AREA -t TAG -n "notes" --every PATTERN --until DATE --parent <id>
tdo move extras: --clear-schedule --clear-deadline --clear-recurrence
Complete / Delete / Restore
tdo done <id> [<id>...] # complete task(s)
tdo done <id> --note "message" # complete with a note
tdo done <id> --stop # complete and stop recurring task from repeating
tdo delete <id> # soft-delete (move to trash)
tdo restore <id> # restore from trashDependencies & Subtasks
tdo depend <blocked-id> --on <blocker-id> # add dependency
tdo depend <blocked-id> --remove <blocker-id> # remove dependency
tdo add "Sub" --parent <parent-id> # create subtaskAreas & Projects
tdo create area "Name" # create area
tdo remove area "Name" # delete area (and all contents)
tdo create project "Name" [--area AREA] # create project
tdo done <slug> # complete project (via move command)
tdo remove project <slug> # delete project
tdo list areas|projects|tags
tdo edit area|project <name> --new-name "New"Slugs are auto-generated: "My Project" → my-projectContext (orientation snapshot)
tdo context # full situational snapshot (pretty)
tdo context --json # machine-readable snapshotShows: today summary, ready tasks, blocked tasks, overdue, recent completions, inbox count, active projects.
Completions
tdo completion bash|zsh|fish|powershell # generate shell completionsDates
Natural: today tomorrow monday–sunday next-week next-monday ISO (preferred): 2026-03-15
Exit Codes & Gotchas
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Runtime error (task/project not found) |
| 2 | Validation error (conflicting flags, bad date) |
tdo removeis for areas/projects only — usetdo deletefor tasks- Prefer numeric IDs over fuzzy names (
tdo done 42nottdo done "review") - Prefer ISO dates over natural language for scripting
- Check project/area exists before assigning (
tdo list projects)
Agent Conventions
Tags
| Tag | Meaning |
|---|---|
agent | Task assigned to an AI agent |
needs-review | Agent completed work, human review needed |
blocked-human | Agent cannot proceed, human input required |
Agent Queue
tdo view today --tag agent --ready # agent's actionable tasks (excludes blocked)
tdo view inbox --tag agent --ready # agent inbox tasksHuman Review Queue
tdo view inbox --tag needs-review # tasks awaiting human review
tdo view today --tag blocked-human # tasks blocked on human inputWorkflows
Agent starting a session:
tdo context --json # full orientation snapshot
tdo view today --tag agent --ready --json # agent-specific actionable tasksAgent completing work:
tdo done 42 --note "Implemented feature X, added tests"
tdo move 42 -t needs-review # flag for human review (before completing)Human reviewing agent work:
tdo view inbox --tag needs-review
tdo done 42 --note "Reviewed and approved"Agent blocked on human input:
tdo move 42 -t blocked-human --note "Need clarification on API design"