Mastering Taskwarrior

The Command-Line Task Management Powerhouse

#taskwarrior, #commandlinetools

If you're the kind of person who lives in a terminal window, loves control, and believes in tracking life through lists, Taskwarrior might just be the productivity companion you never knew you needed.

In this guide, we'll go beyond the basics and dig deep into advanced usage, integrations, scripting, and automation. You'll walk away with the power to bend Taskwarrior to your workflow.

🛠️ Installation

Taskwarrior is available across multiple platforms:

Linux

# Debian / Ubuntu
sudo apt install taskwarrior

# Fedora
sudo dnf install task

# Arch Linux
sudo pacman -S task

macOS

# Homebrew
brew install task

Windows

Only Option: Windows Subsystem for Linux (WSL)

# Install WSL first from Microsoft Store or:
wsl --install

# Then in your WSL terminal:
sudo apt install taskwarrior

Note: Taskwarrior does not have native Windows support or official packages for Windows package managers (Chocolatey/Scoop). WSL is the only supported method for running Taskwarrior on Windows.

Build from Source

You can also build from source via taskwarrior.org/download for any platform.

After installation, initialize your task database:

task

Note for Taskwarrior 3.x users: If upgrading from 2.x, you'll need to export your old data and import it into the new SQLite-based storage system. See the upgrade guide.

📋 Essential Concepts

Understanding these core concepts will help you master Taskwarrior:

Tasks have attributes like description, project, priority, due date, tags, and annotations
Everything is stored locally in ~/.task/ directory
- Taskwarrior 2.x: Plain text .data files
- Taskwarrior 3.x: SQLite database (taskchampion.sqlite3)
Offline-first design means it works without internet connectivity
Human-readable dates like "tomorrow", "next week", "eom" (end of month)
Flexible filtering lets you slice and dice your task list in powerful ways

🔍 Command Structure

Taskwarrior commands follow this logical structure:

task [filter] [command] [modifications]

Examples:

# List all work tasks due before tomorrow
task +work due.before:tomorrow list

# Mark task 5 as done
task 5 done

# Add a high-priority task to the blog project
task add "Write Taskwarrior article" project:blog priority:H due:friday

⚙️ Core Commands

Command	Description	Example
`add`	Add a new task	`task add "Buy groceries"`
`list` (default)	Show tasks matching filter	`task +home list`
`done`	Mark task(s) as completed	`task 5 done`
`delete`	Permanently delete a task	`task 3 delete`
`start`	Start working on a task (timer)	`task 1 start`
`stop`	Stop tracking a task	`task 1 stop`
`modify`	Change task properties	`task 2 modify priority:L`
`annotate`	Add a note to a task	`task 1 annotate "Called client"`
`denotate`	Remove a note from a task	`task 1 denotate "Old note"`
`duplicate`	Copy a task	`task 5 duplicate`
`log`	Add a completed task retroactively	`task log "Yesterday's meeting"`

🏷️ Tags and Projects

Tags are like labels you can apply to any task:

# Add tags when creating
task add "Review code" +urgent +work

# Add/remove tags later
task 5 modify +important
task 5 modify -someoldtag

Projects group related tasks:

# Assign to project
task add "Setup database" project:website

# List all tasks in a project
task project:website list

📅 Due Dates and Time Management

Taskwarrior understands natural language dates and provides convenient shortcuts:

Common Date Formats

# Specific dates
due:2025-06-15
due:15th
due:june15

# Relative dates
due:tomorrow
due:friday
due:next week
due:in 3 days

# Time periods
due:eom     # end of month
due:eow     # end of week  
due:eoy     # end of year
due:som     # start of month
due:sow     # start of week
due:soy     # start of year

Date Filtering Examples

# Tasks due before specific times
task due.before:tomorrow list
task due.before:eow list
task due.before:2025-07-01 list

# Tasks due after specific times
task due.after:today list
task due.after:eom list

# Overdue tasks
task due.before:today list

🎯 Priorities and Status

Priority Levels

priority:H    # High
priority:M    # Medium  
priority:L    # Low
priority:     # No priority (remove priority)

Task Status

pending - Default for new tasks
completed - Finished tasks
deleted - Removed tasks
waiting - Tasks on hold

# Filter by status
task status:pending list
task status:completed list

# Put task on hold until specific date
task 5 modify wait:friday

🔍 Advanced Filtering

The real power of Taskwarrior lies in its filtering capabilities:

Basic Filters

Filter Type	Syntax	Example
Has tag	`+tagname`	`+work +urgent`
Missing tag	`-tagname`	`-someday`
Project	`project:name`	`project:website`
Priority	`priority:H/M/L`	`priority:H`
Due date	`due:date`	`due:tomorrow`
Description contains	`description.contains:text`	`description.contains:email`

Date Range Filters

# Due this week
task due.after:sow due.before:eow list

# Due in the next 3 days
task due.after:today due.before:3days list

# Overdue tasks
task due.before:today status:pending list

Complex Filter Combinations

# High priority work tasks due this week
task +work priority:H due.before:eow list

# Personal tasks without a due date
task project:personal due: list

# Everything except someday tasks
task -someday status:pending list

📊 Custom Reports

Create personalized views of your tasks by defining custom reports in ~/.taskrc:

# Weekly agenda report
report.agenda.columns=id,project,priority,description,due
report.agenda.labels=ID,Proj,Pri,Description,Due
report.agenda.filter=status:pending due.before:eow
report.agenda.sort=due+,priority-

# High priority items
report.urgent.columns=id,project,description,due,urgency
report.urgent.labels=ID,Project,Task,Due,Urg
report.urgent.filter=status:pending priority:H
report.agenda.sort=urgency-

# Waiting tasks
report.waiting.columns=id,project,description,wait
report.waiting.labels=ID,Project,Description,Wait Until
report.waiting.filter=status:waiting

Then use them:

task agenda
task urgent  
task waiting

🔄 Recurring Tasks

Set up tasks that automatically repeat:

# Basic recurring tasks
task add "Pay rent" due:1st recur:monthly
task add "Weekly review" due:friday recur:weekly
task add "Backup files" due:sunday recur:weekly

# More complex patterns
task add "Quarterly planning" due:2025-07-01 recur:quarterly
task add "Annual review" due:2025-12-31 recur:yearly

Recurrence Options:

daily, weekly, biweekly, monthly, quarterly, yearly
2weeks, 3months (custom intervals)
weekdays (Monday through Friday only)

Managing Recurring Tasks:

# Complete current instance, create next
task 5 done

# Skip current instance without completing
task 5 delete

# Stop the recurrence entirely  
task 5 modify recur:

🔌 Synchronization (Taskwarrior 3.x)

⚠️ BREAKING CHANGE: Taskwarrior 3.0+ completely removed Taskserver/taskd support.

New Sync Options in 3.x

Cloud Storage Backend (Recommended) Sync using cloud storage providers like Google Drive, Dropbox, or AWS S3:

# In ~/.taskrc - example with Google Drive
sync.server.origin=https://drive.google.com/your-folder
sync.server.client_id=your-client-id
sync.encryption_secret=your-encryption-key

TaskChampion Sync Server A new sync server (still in development):

More secure with encrypted data
Requires manual setup and deployment
Limited documentation currently available

Migration from Taskwarrior 2.x

If upgrading from 2.x:

# Export from Taskwarrior 2.x
task export > tasks.json

# Install Taskwarrior 3.x, then import
task import tasks.json

Note: See the official upgrade guide for detailed migration instructions.

⚙️ Hooks and Automation

Taskwarrior supports event-driven hooks that run scripts when certain actions occur:

Available Hook Events

on-add - When a task is added
on-modify - When a task is modified
on-exit - When Taskwarrior exits
on-launch - When Taskwarrior starts

Example: Desktop Notifications

Create ~/.task/hooks/on-add.notify:

#!/bin/bash
# Notify when a task is added
if command -v notify-send >/dev/null; then
    notify-send "Task Added" "$4"
fi

Make it executable:

chmod +x ~/.task/hooks/on-add.notify

Example: Automatic Time Tracking

Create ~/.task/hooks/on-modify.timetrack:

#!/bin/bash
# Log task starts/stops to a file
if [[ "$1" == "api" ]]; then
    echo "$(date): Task $3 $5" >> ~/.task/time.log
fi

🤖 Scripting and JSON Export

Export your tasks as JSON for integration with other tools:

Basic JSON Export

# Export all tasks
task export

# Export filtered tasks
task +work status:pending export

# Pretty-print with jq
task export | jq '.'

Useful JSON Queries with jq

# Get high priority tasks
task export | jq '.[] | select(.priority=="H")'

# Count tasks by project
task export | jq 'group_by(.project) | .[] | {project: .[0].project, count: length}'

# Find overdue tasks
task export | jq --arg today "$(date -I)" '.[] | select(.due < $today and .status == "pending")'

# Get tasks modified today
task export | jq --arg today "$(date -I)" '.[] | select(.modified | startswith($today))'

Integration Examples

# Create a simple dashboard
#!/bin/bash
echo "=== Task Summary ==="
echo "Pending: $(task +PENDING count)"
echo "Completed today: $(task end:today count)"
echo "Overdue: $(task +OVERDUE count)"
echo ""
echo "=== Urgent Tasks ==="
task priority:H due.before:eow list

🔧 Configuration Tips

Key configuration options in ~/.taskrc:

# Date format
dateformat=Y-M-D H:N
dateformat.report=Y-M-D
dateformat.annotation=Y-M-D

# Default command (what happens when you type just 'task')
default.command=next

# Urgency calculation (affects task ordering)
urgency.user.project.website.coefficient=5.0
urgency.user.tag.urgent.coefficient=10.0
urgency.due.coefficient=12.0

# Color themes
include /usr/share/taskwarrior/dark-256.theme

# Confirmation prompts
confirmation=yes

# Bulk operations limit
bulk=100

🚀 Productivity Workflows

Getting Things Done (GTD) Setup

# Inbox for quick capture
task add "Call dentist" +inbox

# Weekly review process
task +inbox list              # Process inbox
task project: list            # Review unprojectized tasks
task +waiting list            # Check waiting items
task +someday list            # Review someday/maybe

Daily Workflow

# Morning routine
alias morning='task +OVERDUE list; task due:today list; task +urgent list'

# End of day review  
alias evening='task completed today; task +next limit:5'

# Quick add with inbox processing
alias in='task add +inbox'

Context-Based Organization

# Location contexts
task add "Buy groceries" +errands
task add "Review code" +computer  
task add "Call mom" +phone

# Energy-level contexts
task add "Organize files" +lowenergy
task add "Write proposal" +highenergy

🛠️ Troubleshooting

Common Issues and Solutions

Task database corruption:

# Check database integrity
task diagnostics

# Repair if needed
task repair

Sync conflicts:

# Force push local changes
task sync init

# Reset to server state (destructive!)
task sync reset

Performance with large task lists:

# Archive old completed tasks
task status:completed end.before:6months delete

# Use gc to clean up
task gc

📚 Resources and Learning

Official Documentation

Community Resources

Related Tools

Timewarrior - Time tracking companion
Vit - Curses-based task interface
Tasksh - Interactive shell for Taskwarrior
Various mobile apps that sync with Taskserver

🎯 Final Thoughts

Taskwarrior isn't just a todo list—it's a command-line productivity engine that grows with your needs.

The key to mastering Taskwarrior is to start simple and gradually incorporate more advanced features as they become useful to your workflow. Don't try to use every feature at once; instead, focus on the core commands and filters that solve your immediate needs.

Once you master its syntax and mindset, Taskwarrior stops being a task manager and starts becoming an extension of your thought process—allowing you to capture, organize, and execute on your ideas with unprecedented speed and flexibility.

Thank you for reading. Now go forth and take command of your tasks—one keystroke at a time.