tasks-cli-rs 0.13.0

# tasks-cli-rs

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

## Implementation Status

v0.1 is implemented (see [ROADMAP.md](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`
- Quick due dates everywhere `--due`/`-d` is accepted (new/set/filters):
  `today`, `tomorrow`, `+3d`, `+2w`, `fri` (next such weekday), `8-15`
  (nearest future MM-DD), or full `YYYY-MM-DD`
- Editor: `tasks edit <id>`, `tasks edit --lib` (auto-detection chain)
- Filters: `tasks list --status/--tag/--priority/--due-before/--due-after`;
  done/cancelled are hidden by default — `--all` (or an explicit `--status`)
  shows them, and `--dir archive/...` browses archives unfiltered
- 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`

```bash
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:

```bash
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`):

```markdown
---
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:**

```bash
# 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:**

```bash
# 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

```bash
# 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:**

```bash
# 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):**

1. `--editor` CLI flag
2. `TASKS_EDITOR` environment variable
3. `editor` field in `~/.tasks-cli/config.toml`
4. `$VISUAL` environment variable
5. `$EDITOR` environment variable
6. 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.

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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.

```bash
# 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.).

```bash
# 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`.

```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:**

```bash
# 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:**

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
cargo install tasks-cli-rs
```

### From source

```bash
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
# Bash
tasks completions bash >> ~/.bashrc

# Zsh
tasks completions zsh >> ~/.zshrc

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

## Quick Start

```bash
# 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 did <title>` | Record an already-finished item (born done); supports `--tag` and `-m <note>` |
| `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
- [x] Steps (sub-task management) with dependencies and progress tracking
- [x] Task dependencies (blocks / blocked-by)
- [x] Task aliases for quick reference
- [x] Task pinning
- [x] Time tracking (start/stop with weekly reports)
- [x] Priority matrix view (Eisenhower matrix)
- [x] Undo / action log
- [x] 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](LICENSE) for details.