Usage guide

Task lifecycle

Every task moves through four statuses:

1. todo – not started (default)
2. in_progress – actively being worked on
3. in_review – waiting for review or feedback
4. done – completed

Use oru start, oru review, and oru done as shortcuts, or set the status explicitly with oru update $ID -s $STATUS.

Adding tasks

$ oru add "Fix login bug"$ oru add "Fix login bug" -p high -d friday$ oru add "Write docs" -l docs -n "Include API section"$ oru add "Deploy v2" -s todo -d 2026-03-01 --assign alice

Options:

Listing tasks

$ oru list$ oru list -s in_progress -p high$ oru list -l backend --sort due --actionable$ oru list --search "login" --all

By default, list hides tasks with status done. Add --all to include them.

Filtering

Sorting

Use --sort to change the order. Default is priority. Available fields: priority, due, title, created.

Pagination

Use --limit and --offset for paginated results.

Getting a single task

$ oru get hJ7kMp3nQrs$ oru get hJ7kMp3nQrs --json

You can use a full ID or a unique prefix. If the prefix is ambiguous (matches multiple tasks), oru will tell you and list the matches.

Updating tasks

$ oru update hJ7kMp3nQrs -s in_progress$ oru update hJ7kMp3nQrs -l urgent -d tomorrow$ oru update hJ7kMp3nQrs -n "Blocked on API review"$ oru update hJ7kMp3nQrs -t "New title" -p high

Labels are additive by default. Use --unlabel to remove a label:

$ oru update hJ7kMp3nQrs --unlabel wontfix

Clear the due date or owner by passing none:

$ oru update hJ7kMp3nQrs -d none$ oru update hJ7kMp3nQrs --assign none

Editing in $EDITOR

For complex edits, open a task in your editor:

$ oru edit hJ7kMp3nQrs$ EDITOR=nano oru edit hJ7kMp3nQrs

The file is a TOML block delimited by +++, followed by a notes section:

+++title = "Fix login bug"status = "todo"priority = "high"blocked_by = []labels = []+++# Notes# Add new notes below. Delete lines to remove notes.- Reproduced on staging

Status shortcuts

Quick commands to change task status. Accept one or more IDs:

$ oru start hJ7kMp3nQrs       # -> in_progress$ oru review hJ7kMp3nQrs      # -> in_review$ oru done hJ7kMp3nQrs wX2y   # -> done (multiple)

Labels

Labels are freeform strings. Add them when creating or updating tasks:

$ oru add "Fix bug" -l bug frontend$ oru list -l bug$ oru labels

The labels command lists all labels currently in use across your tasks.

Notes

Notes are append-only comments on a task. Add a note with -n on add or update:

$ oru update hJ7kMp3nQrs -n "Discussed in standup, moving to next sprint"

Clear all notes with --clear-notes. You can combine --clear-notes with -n to replace all notes with a single new one.

Due dates

oru supports natural language date parsing. Input is case-insensitive.

$ oru add "Ship feature" -d tomorrow$ oru add "Sprint review" -d Friday$ oru add "Quarterly report" -d 2026-03-01$ oru add "Standup" -d "tod 10a"$ oru add "Call" -d "in 3 days"$ oru add "Deadline" -d "end of month"

Recurring tasks

Create tasks that auto-spawn the next occurrence when completed:

$ oru add "Water plants" -r "every 3 days" -d today$ oru add "Weekly review" -r "every monday" -d "next monday"$ oru add "Monthly report" -r "every month" -d "end of month"

Supported patterns:

When you mark a recurring task as done, oru automatically creates the next occurrence with the same title, priority, labels, and recurrence rule.

Removing recurrence

Use --repeat none on update to stop a task from recurring. The current task remains; it just won’t spawn a new occurrence when completed.

$ oru update 019414a3 -r none

Blocked-by dependencies

Tasks can be blocked by other tasks:

$ oru add "Deploy" -b abc123 def456$ oru update xyz789 -b abc123$ oru update xyz789 -b abc123 def456  # replaces the full blocked-by list

Use --actionable to filter to tasks with no incomplete blockers:

$ oru list --actionable

Context

Get a summary of what needs your attention:

$ oru context$ oru context --json

Returns:

• Overdue tasks
• Due soon (within 48 hours)
• In progress tasks
• Actionable tasks (not blocked, not done)
• Blocked tasks
• Recently completed tasks

Change history

View the change history of a task:

$ oru log hJ7kMp3nQrs

$ oru log hJ7kMp3nQrs --json

Deleting tasks

$ oru delete hJ7kMp3nQrs$ oru delete hJ7kMp3nQrs wX2yBv5uTzA  # multiple

Deleted tasks are removed from the database but the operation is logged in the oplog for sync purposes.

Sync

Sync between machines via a shared filesystem (Dropbox, iCloud Drive, NAS):

$ oru sync ~/Dropbox/oru-sync

Conflict resolution is automatic: last-write-wins per field, updates beat deletes, notes append with dedup.

Backup

Create manual backups:

$ oru backup              # to default location

$ oru backup ~/backups/

Or configure automatic backups in ~/.oru/config.toml:

backup_path = "~/Dropbox/oru-backups"backup_interval = 60  # minutes between auto-backups

Self-update

Update oru to the latest version:

$ oru self-update