Where does Taskwarrior store its data?

All tasks live in ~/.task/ as plain text files (pending.data, completed.data, undo.data). You can back them up with any standard file backup tool.

Can I use Taskwarrior without syncing?

Yes. Sync is entirely optional. Everything works locally out of the box and you never need to configure taskd unless you want tasks on multiple machines.

What is the difference between a context and a filter?

A filter is typed inline on a single command (e.g., task project:work list). A context is a saved filter that applies silently to every command until you clear it or switch to another context.

How do I see completed tasks?

Run task completed or task all to list tasks including done and deleted ones. You can still filter by project or tag in these reports.

Is vit the same as taskwarrior-tui?

No. vit is a Python wrapper around Taskwarrior that uses ncurses and reads your existing taskrc. taskwarrior-tui is a separate Rust application with its own configuration and a different visual style. Both are good; vit tends to stay closer to Taskwarrior's native behavior.

Manage Personal Tasks with Taskwarrior

Taskwarrior is a command-line task manager that stores everything in plain files and gets out of your way. It handles one-off tasks, recurring chores, project grouping, and filtering — all from a shell. This guide covers daily workflow, contexts, recurring tasks, syncing with Taskwarrior Server or FreedTaskwarrior, and the vit TUI for when you want a visual overview without leaving the terminal.

Installation

Debian / Ubuntu

sudo apt update && sudo apt install taskwarrior vit

Fedora / RHEL family

sudo dnf install task vit

On RHEL 9 / Rocky 9 you may need EPEL first: sudo dnf install epel-release.

Arch

sudo pacman -S task vit

Confirm the version after install:

task --version

You need at least 2.6 for the features here. Most current LTS releases ship 2.6+; Arch and Fedora stay close to upstream.

Core Workflow: Add, List, Done

Adding tasks

The basic form is task add <description>. You can attach metadata inline:

# Plain task
task add Buy coffee filters

# With a due date and project
task add project:home due:tomorrow Replace kitchen faucet washer

# With a priority (H, M, L)
task add project:work priority:H Submit quarterly report due:2025-08-01

# With tags
task add +shopping +errands Pick up dry cleaning

Listing tasks

# Default report — pending tasks, urgency-sorted
task list

# Filter by project
task project:work list

# Filter by tag
task +shopping list

# Everything due today or overdue
task due.before:tomorrow+1day list

The next report is often more useful day-to-day — it shows the top 25 tasks by urgency:

task next

Completing and deleting tasks

# Mark task 3 done
task 3 done

# Delete a task (marks it deleted, not permanently removed)
task 4 delete

# Undo the last change
task undo

Modifying existing tasks

# Change due date on task 5
task 5 modify due:2025-08-15

# Add a tag to task 5
task 5 modify +urgent

# Move task 5 to a different project
task 5 modify project:personal

Recurring Tasks

Use recur together with due to create tasks that regenerate automatically. Taskwarrior creates the next instance when you complete the current one.

# Weekly team meeting, starting next Monday
task add project:work recur:weekly due:monday Team meeting notes

# Monthly bill payment
task add recur:monthly due:1st Pay electricity bill

# Daily standup reminder with an end date
task add recur:daily due:9am until:2025-12-31 Post standup update

Valid recur values include daily, weekly, biweekly, monthly, quarterly, annual, or a duration like 3days. List recurring tasks specifically:

task recurring list

Contexts

A context is a saved filter that silently applies to every command. Think of it as a lens: you flip context and only see the tasks that matter right now — useful when switching between work, personal, and home modes.

Defining and activating contexts

Contexts were formalized in Taskwarrior 2.6 with the context define sub-command:

# Define contexts
task context define work project:work or +work
task context define personal project:personal or project:home
task context define shopping +shopping

# Activate a context
task context work

# All commands now filter through 'project:work or +work'
task list
task next

Switching and clearing contexts

# Switch context
task context personal

# See current context
task context show

# Remove context (see everything again)
task context none

Contexts are stored in ~/.taskrc so they persist across sessions.

The vit TUI

vit (Visual Interactive Taskwarrior) wraps Taskwarrior in a keyboard-driven ncurses interface. It reads your existing ~/.taskrc and all normal reports work inside it.

vit

Key bindings inside vit:

a — add a new task
Enter — show full task details
d — mark task done
e — edit task (opens your $EDITOR)
D — delete task
u — undo last action
/ — filter tasks inline
q — quit

To open vit on a specific report, pass it as an argument:

vit next
vit project:work list

Configure vit in ~/.vit/config.ini. The most common change is setting a default report:

mkdir -p ~/.vit
cat >> ~/.vit/config.ini <<'EOF'
[taskwarrior]
default_report = next
EOF

Syncing Tasks

Taskwarrior's sync protocol lets you share tasks across machines. Two practical options exist: self-hosted Taskserver (taskd) or the hosted FreedTaskwarrior service. Both use the same client-side config.

Option A: FreedTaskwarrior (hosted, easiest)

FreedTaskwarrior (freedtaskwarrior.org) runs a public Taskserver you can register on for free. After registering you receive a credentials bundle. Download it, then:

# Unpack the credential tarball (filename will vary)
tar xzf freedtaskwarrior-credentials.tar.gz -C ~/.task/

# Point task at the server (values come from your credential files)
task config taskd.server freedtaskwarrior.org:53589
task config taskd.credentials 'YourOrg/YourUser/UUID-here'
task config taskd.certificate ~/.task/your.cert.pem
task config taskd.key ~/.task/your.key.pem
task config taskd.ca ~/.task/ca.cert.pem

Option B: Self-hosted taskd

Install the server on your own machine or VPS:

# Debian/Ubuntu
sudo apt install taskd

# Fedora
sudo dnf install taskd

Full taskd setup (PKI, user creation, firewall) is beyond this guide's scope, but the official Taskserver setup docs are thorough. Once your server is running, the client config steps are identical to Option A.

Syncing

# First sync — pushes all local tasks
task sync init

# Subsequent syncs
task sync

Run task sync on each machine after making changes. There is no daemon; you trigger it manually or via a systemd user timer.

Automating sync with a systemd user timer

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/task-sync.service <<'EOF'
[Unit]
Description=Taskwarrior sync

[Service]
Type=oneshot
ExecStart=/usr/bin/task sync
EOF

cat > ~/.config/systemd/user/task-sync.timer <<'EOF'
[Unit]
Description=Sync Taskwarrior every 15 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=15min

[Install]
WantedBy=timers.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now task-sync.timer

Verification

# Check open tasks and basic stats
task stats

# Confirm sync is live
task sync
# Expected output (will vary): "Sync successful.  2 changes uploaded, 0 downloaded."

# Check timer fires correctly
systemctl --user status task-sync.timer

Troubleshooting

task sync fails with certificate error

Verify the paths in ~/.taskrc for taskd.certificate, taskd.key, and taskd.ca are absolute paths and the files are readable by your user. Also confirm your system clock is accurate — TLS handshakes fail with significant time drift: timedatectl status.

Recurring tasks multiply unexpectedly

If you run task sync across machines before completing an instance on both sides, you can get duplicates. Run task list to spot them by description, then task <id> delete the extras. The task undo command can also reverse accidental completions.

vit shows nothing / blank screen

vit defaults to the next report. If no tasks match (e.g., an active context filters everything out), the list is genuinely empty. Run task context none then relaunch vit to confirm tasks exist.