tasks-cli

A plain-text personal task system. Either work from the command line or manually edit tasks.md; all other files are generated and managed by the CLI and scripts.

Zero dependencies — pure Python 3 stdlib.

Quick setup

1. Clone the repo:

git clone https://github.com/YOUR_USERNAME/tasks-cli.git ~/tasks-cli

2. Copy the template to create your task file:

cp ~/tasks-cli/tasks.template.md ~/tasks-cli/tasks.md

3. Add this alias to ~/.zshrc (or ~/.bashrc):

alias tasks='python3 ~/tasks-cli/bin/tasks.py'

4. Reload your shell:

source ~/.zshrc

5. Verify:

tasks

If the alias isn't active yet, invoke directly:

python3 ~/tasks-cli/bin/tasks.py

Note: tasks.md, archive.md, week_overview.md, and week_state.json are gitignored — your personal task data stays local and never gets committed.

Files

• tasks.md — source of truth (the only file you edit manually). Gitignored.
• tasks.template.md — starter structure to copy from.
• bin/tasks.py — unified CLI.
• archive.md — append-only completed task history (generated). Gitignored.
• week_overview.md — regenerated on every tasks sync. Gitignored.
• week_state.json — current week state and completed-this-week cache. Gitignored.
• com.devlog.tasksync.plist — optional launchd template (macOS).

Core usage

• Just run "tasks" for a run down of usage flags and options.

Add tasks

Interactive guided mode:

tasks add

Inline mode:

tasks add "Description" -pj ProjectName -pr high -due 2026-03-20

Optional flags:

• -pj|--project PROJECT
• -pr|--priority high|med|low
• -due|--due YYYY-MM-DD
• -rep|--repeat Mon-Sun
• -st|--status hold|backburner

Process completions + regenerate overview

tasks sync

Backfill/test for a specific date:

tasks sync --date YYYY-MM-DD

Query views

tasks today
tasks overdue
tasks high
tasks med
tasks low
tasks hold
tasks backburner
tasks week
tasks next
tasks myproject   # any project name — case-insensitive

Tag format in tasks.md

• Project: #proj/<Project>
• Priority: p:high|med|low
• Due date: due:YYYY-MM-DD
• Repeating: repeat:weekly day:Mon|Tue|Wed|Thu|Fri|Sat|Sun
• Status: status:hold|backburner

System behaviour

• Non-repeating completed tasks (- [x]) are archived to archive.md.
• Repeating completed tasks are reset back to unchecked so they recur.
• tasks sync updates week_state.json and rebuilds week_overview.md.
• Week rollover is automatic (no manual reset required).

Using from a different directory

tasks --base /path/to/your/tasks/dir

Optional automation (launchd — macOS)

cp ~/tasks-cli/com.devlog.tasksync.plist ~/Library/LaunchAgents/
launchctl unload ~/Library/LaunchAgents/com.devlog.tasksync.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.devlog.tasksync.plist

Ensure the plist runs:

python3 ~/tasks-cli/bin/tasks.py sync