Skip to content

usage.md

Latest commit

 

History

History
250 lines (180 loc) · 7.5 KB

usage.md

File metadata and controls

250 lines (180 loc) · 7.5 KB
Raw

Usage

Features

Tod supports common Todoist workflows from the command line:

  • Create tasks with Todoist quick-add and natural language syntax.
  • Import projects and create, list, schedule, prioritize, and process tasks by project.
  • View and update groups of tasks with Todoist filters.
  • Add task comments, edit tasks, complete tasks, and move through one task at a time.
  • Label, schedule, prioritize, and process tasks in interactive or scripted flows.
  • Automatically adapt task and comment output to the current CLI window size.

Discovering the commands

Run tod -h to see all available commands and global flags. Key global flags:

  • --json / -j — Output results as JSON for machine-readable consumption. Suppresses interactive prompts and spinners.
  • --timeout / -t — Time to wait for API responses in seconds (default: 30).
  • --verbose / -v — Display additional debug info while processing.
  • --config / -c — Absolute path to configuration file (default: $XDG_CONFIG_HOME/tod.cfg).

Use tod <command> -h to see subcommands and flags for each command group.

And also use it to dig into subcommands

> tod task -h

Commands for individual tasks

Usage: tod task <COMMAND>

Commands:
  quick-add      (q) Create a new task using NLP
  create         (c) Create a new task (without NLP)
  edit           (e) Edit an existing task's content
  next           (n) Get the next task by priority
  complete       (o) Complete the last task fetched with the next command
  reopen         (r) Reopen the last completed task
  comment        (m) Add a comment to the last task fetched with the next command
  edit-comment   (ec) Edit an existing comment's content
  delete-comment (dc) Delete a comment by ID
  help           Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
> tod auth -h

(a) Commands for logging in with OAuth or managing API tokens

Usage: tod auth <COMMAND>

Commands:
  login  (l) Log into Todoist using OAuth
  token  (t) Save a Todoist developer API token directly to the config (non-interactive)
  view   (v) Display the current Todoist API token
  help   Print this message or the help of the given subcommand(s)

Usage Examples

# Set your Todoist API token directly (non-interactive, great for CI/scripting)
tod auth token YOUR_API_TOKEN

# Log in with OAuth (interactive, opens a browser)
tod auth login

# Quickly create a task
tod task quick-add --content Buy more milk today

# Quickly create a task with aliases
tod t q -c Buy more milk today

# You can use Todoist syntax with the quickadd (q) command
# See https://todoist.com/help/articles/use-task-quick-add-in-todoist-va4Lhpzz for more details
tod t q -c Buy more milk today // with a description

# Set a reminder
tod t q -c Buy more milk today ! today 2pm

# creates a task named "Clean my room" due on Tuesday at 1pm, with Priority of 2
tod t q -c Clean my room on tuesday at 1pm p2

# creates a task in the eBay project, an errands label, priority of 2, due tomorrow.
tod t q -c Ship UPS Package #eBay @errands p2 tomorrow

## Other Usage Examples

# Create a new task (you will be prompted for content and project)
tod task create

# Create a task in a project
tod task create --content "Write more rust" --project code

# Create a subtask under an existing task
tod task create --content "Add tests" --project code --parent-id 1234567890

# Import your projects
tod project import
tod project import -p work # or --id 123

# Import all projects in Todoist into Tod
tod project import -a

# Update a project
tod project update -p "My Project" -n "Renamed Project" -c "red"
tod project update --project "Work" --is-favorite true
tod project update -p "Side Project" -v "board"

# Archive / unarchive a project
tod project archive -p "Old Project"
tod project unarchive -p "Old Project"

# Create a section in a project
tod section create -s "Groceries" -p "Shopping"

# Delete a section from a project (interactive: pick project, section, confirm)
tod section delete

# Delete a section by name
tod section delete -s "Groceries" -p "Shopping"

# Skip confirmation when deleting a section (tasks inside will also be deleted)
tod section delete -s "Groceries" -p "Shopping" --force

# Repeat mode — keep deleting sections until Ctrl+C
tod section delete -r

# Create a label
tod label create --name "Urgent" --color red

# Create a label with favorite and order
tod label create -n "Personal" -c blue -f -o 1

# Update a label
tod label update --label "Urgent" --name "Critical"
tod label update -l "Personal" --color purple

# Delete a label (skip confirmation)
tod label delete --label "Critical" --force

# Delete a label (interactive prompt)
tod label delete -l "Purple"
# Get the next task for a project
tod task next

# Comment on the current (next) task
tod task comment

# Edit an existing comment by ID
tod task edit-comment 1234567890 "Updated comment text"

# Edit a comment with JSON output
tod task edit-comment 1234567890 "Updated comment text" --json

# Edit a comment (interactive prompt for new content)
tod task edit-comment 1234567890

# Delete a comment by ID
tod task delete-comment 1234567890

# Delete a comment with JSON output
tod task delete-comment 1234567890 --json

# Go through tasks with an interactive prompt, completing them in order of importance one at a time.
tod list process

# Complete the last "next task" and get another
tod task complete && tod task next

# Reopen the last completed task
tod task reopen

# Get all tasks for work
tod list view --project work

# Get all tasks in three groupings, overdue, today, and tomorrow
tod list view --filter overdue,today,tom

# Generate shell completions for fish
tod shell completions fish > ~/.config/fish/completions/tod.fish

# Label all tasks with no label either physical or digital
tod list label --filter "no label" --label physical --label digital

Shell script examples

Sort, schedule, prioritize, and process tasks

  echo "" && \
  echo "=== EMPTYING INBOX ===" && \
  tod project empty --project inbox && \
  echo "" && \
  echo "=== SCHEDULING DIGITAL ===" && \
  tod list schedule --project digital && \
  echo "" && \
  echo "=== SCHEDULING PHYSICAL ===" && \
  tod list schedule --project physical && \
  echo "" && \
  echo "=== PRIORITIZING DIGITAL ===" && \
  tod list prioritize --project digital && \
  echo "" && \
  echo "=== PRIORITIZING PHYSICAL ===" && \
  tod list prioritize --project physical
  echo "" && \
  echo "=== PROCESSING DIGITAL ===" && \
  tod list process --project digital && \
  echo "" && \
  echo "=== PROCESSING PHYSICAL ===" && \
  tod list process --project physical;

How task priority is determined

See sort_order

Use --sort or --sort value to apply the configured sort order. Explicit alternatives remain available with --sort datetime and --sort todoist.

Update Tod

tod config check-version

Update Tod (no prompt)

tod config check-version --force

Tod will attempt to detect the installed method (homebrew, cargo, scoop, etc) and auto-update if possible.