tasks-cli-rs-0.10.1 is not a library.

tasks-cli-rs

A powerful, Markdown-based TODO task management CLI tool written in Rust.

Implementation Status

v0.1 is implemented (see ROADMAP.md):

Task libraries: tasks lib add/list/use/current/remove
CRUD: tasks new/list/show/delete
Lifecycle: tasks start/done/cancel/status (automatic timestamps)
Field edits: tasks set --title/--priority/--due/--tag-add/--tag-remove
Editor: tasks edit <id>, tasks edit --lib (auto-detection chain)
Filters: tasks list --status/--tag/--priority/--due-before/--due-after
Search: tasks search <text>; tags: tasks tag add/remove/list
Task ids: sequence number (1, #1) or UUID short id prefix

Recurring tasks: tasks recur add/list/show/pause/resume/remove/tick

tasks recur add "每日站会" --rule daily --tag daily
tasks recur add "周报" --rule weekly:fri --until 2026-12-31
tasks recur add "月度对账" --rule monthly:1,15 --max-count 6
tasks recur add "浇花" --rule every:3d --start 2026-08-01

Rules live in .recurring/ inside the library and generate ordinary task files. Dates are local calendar dates, and monthly:31 clamps to the last day of shorter months. There is no daemon: every command materialises whatever is due first, so missed cycles collapse into a single task for the latest one. A new cycle is generated even when the previous instance is still open.

Build and test:

cargo build --release
cargo test

Everything below this section is the original design document; features not listed above are not yet implemented.

Overview

tasks-cli-rs is a command-line tool that treats each TODO item as a Markdown file, stored and organized on the filesystem. It provides a seamless task management experience with rich features including Kanban board view, sync support, tags, lifecycle tracking, and smart editor integration.

Features

1. Markdown-Based Task Storage

Each task is stored as an individual Markdown (.md) file. The file contains structured front matter (YAML) for metadata and free-form Markdown body for task description and notes.

Task file format example (tasks/work/implement-auth.md):

---
id: 550e8400-e29b-41d4-a716-446655440000
title: Implement user authentication
status: in_progress
priority: high
tags: [backend, security, auth]
created_at: 2026-07-01T09:00:00Z
started_at: 2026-07-02T10:00:00Z
due_date: 2026-07-20T23:59:59Z
completed_at: null
steps:
  - id: s1
    title: Design token schema
    status: done
  - id: s2
    title: Implement login endpoint
    status: in_progress
    due_date: 2026-07-15
  - id: s3
    title: Add refresh token support
    status: todo
  - id: s4
    title: Write integration tests
    status: todo
    depends_on: [s2, s3]
---

## Description

Implement JWT-based authentication for the REST API.

## Notes

Use RS256 algorithm. Tokens should expire after 15 minutes.

Task filesystem layout:

~/.tasks-cli/                    # Default base directory
├── config.toml                  # Global configuration
├── libraries.toml               # Registered task libraries
└── repos/
    ├── personal/                # A task library (project)
    │   ├── .tasks-meta.toml     # Library metadata
    │   ├── inbox/
    │   ├── work/
    │   └── personal/
    └── work-projects/           # Another task library
        ├── .tasks-meta.toml
        ├── feature-a/
        └── bugfixes/

2. Task Library Management

A task library is a root directory containing a collection of tasks organized into subdirectories. Users can maintain multiple libraries (e.g., personal, work) and switch between them as the active default.

Commands:

# Add a new library
tasks lib add <name> <path>
tasks lib add personal ~/tasks/personal

# List all registered libraries
tasks lib list

# Switch the active (default) library
tasks lib use <name>
tasks lib use work-projects

# Show currently active library
tasks lib current

# Remove a library from the registry (does not delete files)
tasks lib remove <name>

3. Task Lifecycle Management

Tasks follow a clearly defined lifecycle. Users can explicitly mark transitions.

Lifecycle states:

Status	Description
`todo`	Created, not yet started
`in_progress`	Work has been started
`blocked`	Waiting on an external dependency
`in_review`	Work done, pending review
`done`	Completed
`cancelled`	Explicitly cancelled

Commands:

# Mark a task as started (sets started_at timestamp)
tasks start <task-id-or-slug>

# Mark a task as done (sets completed_at timestamp)
tasks done <task-id-or-slug>

# Set arbitrary status
tasks status <task-id-or-slug> <status>

# Cancel a task
tasks cancel <task-id-or-slug>

4. Task CRUD Operations

# Create a new task
tasks new "Task title"
tasks new "Fix login bug" --priority high --tag backend --tag bugfix --due 2026-07-20

# List tasks
tasks list                          # All tasks in active library
tasks list --status todo            # Filter by status
tasks list --tag backend            # Filter by tag
tasks list --due-before 2026-08-01  # Filter by due date
tasks list --priority high          # Filter by priority
tasks list --dir work/              # List tasks in a subdirectory

# Show task details
tasks show <task-id-or-slug>

# Delete a task
tasks delete <task-id-or-slug>

# Search tasks
tasks search "authentication"
tasks search --tag security --status in_progress

5. Task Editing

Open a task's Markdown file in an external editor. The editor is selected based on the environment:

SSH / headless environment: defaults to $EDITOR or vim
Desktop environment: auto-detects and supports VSCode (code), Zed (zed), Neovim, etc.

Commands:

# Edit a task in the default editor
tasks edit <task-id-or-slug>

# Edit with a specific editor
tasks edit <task-id-or-slug> --editor code
tasks edit <task-id-or-slug> --editor vim

# Open the task library root in an editor
tasks edit --lib

Editor detection logic (priority order):

--editor CLI flag
TASKS_EDITOR environment variable
editor field in ~/.tasks-cli/config.toml
$VISUAL environment variable
$EDITOR environment variable
Auto-detection: checks if running in SSH session ($SSH_TTY/$SSH_CONNECTION), then prefers terminal editors (vim, nano); otherwise checks for desktop editors (code, zed, nvim)

6. Tag Management

Tags are stored in the YAML front matter of each task file.

# Add tags to a task
tasks tag add <task-id> <tag> [<tag> ...]
tasks tag add abc123 backend security

# Remove tags from a task
tasks tag remove <task-id> <tag>

# List all tags used across the active library
tasks tag list

# List all tasks with a specific tag
tasks list --tag <tag>

7. Kanban Board View

Display tasks in a Kanban board layout in the terminal, grouped by status columns.

# Show Kanban board for active library
tasks board

# Show board for a specific subdirectory
tasks board --dir work/

# Show board filtered by tag
tasks board --tag backend

# Show board with a specific set of columns
tasks board --columns todo,in_progress,done

Terminal Kanban board example:

┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│      TODO (3)    │ │  IN PROGRESS (2) │ │     DONE (5)     │
├──────────────────┤ ├──────────────────┤ ├──────────────────┤
│ Fix login bug    │ │ Auth impl        │ │ Setup CI/CD      │
│ [high] [bugfix]  │ │ [backend]        │ │ Write unit tests │
│ Due: 2026-07-20  │ │ Due: 2026-07-25  │ │ ...              │
├──────────────────┤ ├──────────────────┤ │                  │
│ Update docs      │ │ Refactor DB      │ │                  │
│ [docs]           │ │ [backend]        │ │                  │
├──────────────────┤ └──────────────────┘ │                  │
│ Add dark mode    │                      │                  │
│ [frontend]       │                      │                  │
│ Due: 2026-08-01  │                      │                  │
└──────────────────┘                      └──────────────────┘

8. Statistics and Reporting

# Show task statistics summary
tasks stats

# Show stats for a specific time range
tasks stats --since 2026-07-01 --until 2026-07-31

# Show stats per tag
tasks stats --by-tag

# Show completion trend (tasks done per day/week)
tasks stats --trend weekly

# Show overdue tasks
tasks overdue

Example stats output:

Task Statistics — personal library
────────────────────────────────────
Total tasks:        47
  Todo:             12
  In Progress:       5
  Done:             28
  Cancelled:         2

Completion rate:    59.6%
Avg. completion:    3.2 days
Overdue:            3 tasks

Top tags:
  backend     ██████████  18
  frontend    ████████    14
  bugfix      █████       9

9. Due Date Reminders

# Check for tasks due soon (default: within 3 days)
tasks remind

# Check for tasks due within a custom window
tasks remind --within 7d

# List overdue tasks
tasks remind --overdue

# Show a summary notification (suitable for shell prompt or cron)
tasks remind --summary

Integrates with the shell prompt for unobtrusive reminders:

# Add to ~/.bashrc or ~/.zshrc for prompt integration
export PS1='$(tasks remind --prompt-badge)'"$PS1"
# Displays: ⚠ 2 due  $ when tasks are approaching due date

10. GitHub Repository Sync

Sync your task library with a GitHub repository, enabling collaboration and backup.

# Configure GitHub sync for a library
tasks sync github setup --repo owner/repo-name --lib personal

# Push local tasks to GitHub
tasks sync github push

# Pull tasks from GitHub
tasks sync github pull

# Sync (pull then push, resolving conflicts)
tasks sync github sync

# Show sync status
tasks sync github status

# Disable sync
tasks sync github disable

Sync behavior:

Uses git under the hood; the task library directory is a git repository.
Each push commits all changes with an auto-generated message and pushes to the configured remote branch.
Conflict resolution: file-level merge using last-write-wins by default; --interactive flag prompts for manual conflict resolution.
Authentication: uses SSH keys or GH_TOKEN environment variable via gh CLI if available.

11. WebDAV Sync

Sync your task library with any WebDAV-compatible server (Nextcloud, ownCloud, etc.).

# Configure WebDAV sync for a library
tasks sync webdav setup \
  --url https://cloud.example.com/remote.php/dav/files/user/tasks \
  --username user \
  --lib personal

# Password is stored in system keychain (uses `keyring` crate)

# Push to WebDAV
tasks sync webdav push

# Pull from WebDAV
tasks sync webdav pull

# Bidirectional sync
tasks sync webdav sync

# Show sync status
tasks sync webdav status

Sync behavior:

Uploads/downloads individual .md files.
Uses ETag-based conflict detection to avoid overwriting newer remote changes.
Deleted files are tracked in .tasks-meta.toml to propagate deletions.

12. Global Configuration

Configuration is stored at ~/.tasks-cli/config.toml.

[general]
active_library = "personal"
date_format = "%Y-%m-%d"
time_format = "%H:%M"

[editor]
default = "vim"
# desktop_prefer = "code"  # Uncomment to prefer VSCode on desktop

[remind]
default_window_days = 3
show_in_prompt = true

[display]
color = true
kanban_column_width = 20
kanban_max_rows = 15

[sync.github]
auto_sync_on_change = false

[sync.webdav]
auto_sync_on_change = false

13. Steps (Sub-task Management)

Steps are ordered sub-tasks within a task, stored in the YAML front matter. Each step has its own status, optional due date, and optional dependencies on other steps.

Step fields:

Field	Required	Description
`id`	yes	Short unique identifier (e.g. `s1`, `s2`)
`title`	yes	Step description
`status`	yes	One of: `todo`, `in_progress`, `done`, `cancelled`
`due_date`	no	Step-level deadline (overrides nothing, informational)
`depends_on`	no	List of step IDs that must be `done` before this step can start

Commands:

# Add a step to a task
tasks step add <task-id> "Design token schema"
tasks step add <task-id> "Write tests" --after s2           # Insert after step s2
tasks step add <task-id> "Deploy" --depends-on s3,s4        # Depends on steps s3 and s4

# List steps for a task
tasks step list <task-id>

# Update step status
tasks step start <task-id> <step-id>    # Mark step as in_progress
tasks step done <task-id> <step-id>     # Mark step as done

# Edit step title
tasks step edit <task-id> <step-id> "Updated title"

# Remove a step
tasks step remove <task-id> <step-id>

# Reorder steps
tasks step move <task-id> <step-id> --before <other-step-id>
tasks step move <task-id> <step-id> --after <other-step-id>

Step progress and task completion:

# Show step progress for a task
tasks show <task-id> --steps

Example output:

Task: Implement user authentication [in_progress]
Priority: high  Due: 2026-07-20  Tags: backend, security

Steps: 1/4 done (25%)
  ━━━━━━━━━━░░░░░░░░░░░░░░░░░░░░░░░░░░░░

  [done]        s1: Design token schema
  [in_progress] s2: Implement login endpoint (due: 2026-07-15)
  [blocked]     s3: Add refresh token support (blocked by: s2)
  [todo]        s4: Write integration tests (blocked by: s2, s3)

Behavior rules:

Task completion percentage is auto-calculated from step statuses (done steps / total steps).
When all steps are marked done, the parent task status is automatically suggested to move to done (user must confirm).
A step with unmet depends_on requirements shows as blocked and cannot be started until all dependencies are done.
Steps are displayed in the Kanban board, stats, and task detail views.
tasks list --steps shows step count and completion percentage in the list output.
tasks board shows a mini progress bar for tasks that have steps.

14. Suggested Optimizations

These are recommended enhancements to improve usability and productivity:

14.1 Task Dependencies and Blocking

# Mark a task as blocked by another task
tasks block <task-id> --by <blocking-task-id>

# Mark a task as depending on another (finishes-before relationship)
tasks depends <task-id> --on <dependency-task-id>

# Show dependency graph
tasks deps --graph          # ASCII graph in terminal
tasks deps --graph --mermaid # Mermaid diagram for docs

A task with unsatisfied dependencies shows a blocked badge.
When the blocking task is marked done, the dependent task's blocked status is auto-cleared to todo.

14.2 Task Aliases

# Create a short alias for a task
tasks alias <task-id> auth-impl

# Use alias in any command
tasks show auth-impl
tasks done auth-impl

Aliases are stored per-library in .tasks-meta.toml.
tasks show auto-resolves slugs (derived from title), IDs, and aliases.

14.3 Natural Language Date Parsing

tasks new "Fix bug" --due "next Friday"
tasks new "Weekly report" --due "every Friday"    # Recurring
tasks remind --within "2 days"

Uses a date parsing library (e.g. chrono + custom parser) to handle relative dates.

14.4 Undo / Action Log

# Undo the last action
tasks undo

# Show recent action history
tasks history --last 20

Every mutation (create, delete, status change, step update) is logged to ~/.tasks-cli/history.jsonl.
tasks undo reverses the last logged action.

14.5 Task Templates

# Save current task as a template
tasks template save <task-id> --name "bugfix-template"

# Create a task from a template
tasks new "Fix login crash" --template bugfix-template

Templates are stored in ~/.tasks-cli/templates/.
Includes tags, steps, and default priority from the source task.

14.6 Priority Matrix View

# Show tasks in an Eisenhower matrix (urgent/important quadrants)
tasks matrix

Example output:

┌─────────────────────────────┐ ┌─────────────────────────────┐
│  URGENT & IMPORTANT         │ │  IMPORTANT, NOT URGENT      │
│  DO FIRST                   │ │  SCHEDULE                   │
├─────────────────────────────┤ ├─────────────────────────────┤
│ • Fix login crash (P1)      │ │ • Refactor auth module (P2) │
│ • Deploy hotfix (P1)        │ │ • Write API docs (P2)       │
└─────────────────────────────┘ └─────────────────────────────┘
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  URGENT, NOT IMPORTANT      │ │  NOT URGENT, NOT IMPORTANT  │
│  DELEGATE                   │ │  ELIMINATE                  │
├─────────────────────────────┤ ├─────────────────────────────┤
│ • Respond to emails (P3)    │ │ • Clean up old branches     │
└─────────────────────────────┘ └─────────────────────────────┘

14.7 Task Pinning

# Pin a task to always show at top of list/board
tasks pin <task-id>

# Unpin
tasks unpin <task-id>

# Show only pinned tasks
tasks list --pinned

14.8 Time Tracking

# Start tracking time on a task
tasks time start <task-id>

# Stop tracking
tasks time stop <task-id>

# Show time logged
tasks time show <task-id>

# Weekly time report
tasks time report --week

Time entries stored in task front matter as time_entries: [{started_at, ended_at}].
Integrates with tasks stats for average completion time calculations.

Installation

From crates.io

cargo install tasks-cli-rs

From source

git clone https://github.com/yourusername/tasks-cli-rs
cd tasks-cli-rs
cargo build --release
sudo cp target/release/tasks /usr/local/bin/

Shell completion

# Bash
tasks completions bash >> ~/.bashrc

# Zsh
tasks completions zsh >> ~/.zshrc

# Fish
tasks completions fish > ~/.config/fish/completions/tasks.fish

Quick Start

# Initialize with a task library in your home directory
tasks lib add personal ~/tasks
tasks lib use personal

# Create your first task
tasks new "Read Rust book" --tag learning --due 2026-08-01

# List tasks
tasks list

# Start working on it
tasks start <task-id>

# Edit notes
tasks edit <task-id>

# Mark done
tasks done <task-id>

# View the Kanban board
tasks board

Command Reference

Command	Description
`tasks new <title>`	Create a new task
`tasks list`	List tasks
`tasks show <id>`	Show task details
`tasks edit <id>`	Edit task in editor
`tasks start <id>`	Mark task as started
`tasks done <id>`	Mark task as done
`tasks cancel <id>`	Cancel a task
`tasks status <id> <status>`	Set task status
`tasks delete <id>`	Delete a task
`tasks search <query>`	Search tasks
`tasks tag add <id> <tag>`	Add tag to task
`tasks tag remove <id> <tag>`	Remove tag from task
`tasks tag list`	List all tags
`tasks step add <id> <title>`	Add a step to a task
`tasks step list <id>`	List steps for a task
`tasks step start <id> <step-id>`	Mark step as started
`tasks step done <id> <step-id>`	Mark step as done
`tasks step edit <id> <step-id> <title>`	Edit step title
`tasks step remove <id> <step-id>`	Remove a step
`tasks step move <id> <step-id>`	Reorder a step
`tasks board`	Show Kanban board
`tasks matrix`	Show Eisenhower priority matrix
`tasks stats`	Show statistics
`tasks remind`	Check reminders
`tasks overdue`	List overdue tasks
`tasks block <id> --by <id>`	Mark task as blocked by another
`tasks depends <id> --on <id>`	Add task dependency
`tasks deps`	Show dependency graph
`tasks alias <id> <name>`	Create task alias
`tasks pin <id>`	Pin task to top of list
`tasks unpin <id>`	Unpin task
`tasks time start <id>`	Start time tracking
`tasks time stop <id>`	Stop time tracking
`tasks time report`	Show time tracking report
`tasks template save <id>`	Save task as template
`tasks undo`	Undo last action
`tasks history`	Show action history
`tasks lib add <name> <path>`	Register a library
`tasks lib list`	List libraries
`tasks lib use <name>`	Switch active library
`tasks lib current`	Show active library
`tasks lib remove <name>`	Remove library
`tasks sync github setup`	Configure GitHub sync
`tasks sync github sync`	Sync with GitHub
`tasks sync webdav setup`	Configure WebDAV sync
`tasks sync webdav sync`	Sync with WebDAV
`tasks completions <shell>`	Generate shell completions

Planned Features

Recently Implemented

Steps (sub-task management) with dependencies and progress tracking
Task dependencies (blocks / blocked-by)
Task aliases for quick reference
Task pinning
Time tracking (start/stop with weekly reports)
Priority matrix view (Eisenhower matrix)
Undo / action log
Task templates

Future Enhancements

Recurring tasks (daily, weekly, monthly)
Natural language date parsing ("next Friday", "in 2 days")
CalDAV sync support
TUI (Terminal User Interface) mode with full keyboard navigation
Export to JSON, CSV, HTML
Import from other tools (Todoist, Things, OmniFocus export formats)
Mobile app companion (read-only sync with mobile clients)
REST API server mode for third-party integrations
Plugin system for custom commands and output formats
Collaborative task sharing (multi-user sync with permissions)

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

License

MIT License. See LICENSE for details.

tasks-cli-rs 0.10.1

tasks-cli-rs

Implementation Status

Overview

Features

1. Markdown-Based Task Storage

2. Task Library Management

3. Task Lifecycle Management

4. Task CRUD Operations

5. Task Editing

6. Tag Management

7. Kanban Board View

8. Statistics and Reporting

9. Due Date Reminders

10. GitHub Repository Sync

11. WebDAV Sync

12. Global Configuration

13. Steps (Sub-task Management)

14. Suggested Optimizations

14.1 Task Dependencies and Blocking

14.2 Task Aliases

14.3 Natural Language Date Parsing

14.4 Undo / Action Log

14.5 Task Templates

14.6 Priority Matrix View

14.7 Task Pinning

14.8 Time Tracking

Installation

From crates.io

From source

Shell completion

Quick Start

Command Reference

Planned Features

Recently Implemented

Future Enhancements

Contributing

License