wshlst 0.1.0

wshlst is a simple task manager CLI

wshlst v0.1.0

wshlst is a small Markdown-first task manager for the command line.

It keeps your tasks in plain .md files under a local .tasks/ directory, with YAML frontmatter for metadata and optional Markdown body content for notes, checklists, or copied source material.

Features

• Add tasks from a title, Markdown file, or URL reference.
• Store tags, priority, due date, status, timestamps, and source metadata.
• List tasks by status, tag, priority, or due date.
• Show the raw Markdown file for a task.
• Update titles, metadata, body content, file sources, and link references.
• Mark tasks as done or archive them without deleting their files.
• Resolve tasks by slug, path, or explicit task(000001) reference.

Installation

This project requires Python 3.11 or newer.

The easiest way to run it locally is with uv:

uv sync
uv run wshlst --help

You can also install it into your current Python environment:

pip install .
wshlst --help

Usage

Run commands from the directory where you want your task list to live. wshlst creates .tasks/ automatically the first time you add a task.

Add tasks

wshlst add "Write project README"
wshlst add "Review API notes" --file notes/api.md
wshlst add "Read release notes" --link https://example.com/release
wshlst add "Ship docs" --tag docs --tag release --priority high --due 2026-06-30

Tasks are stored as numbered Markdown files:

.tasks/
  000001-write-project-readme.md
  000002-review-api-notes.md

Each file contains YAML frontmatter followed by optional Markdown body content:

---
id: '000001'
title: Write project README
status: todo
source:
  type: manual
  value: null
created_at: '2026-06-16T12:00:00Z'
updated_at: '2026-06-16T12:00:00Z'
finished_at: null
priority: normal
tags: []
due: null
---

List tasks

wshlst list
wshlst list --all
wshlst list --done
wshlst list --archived
wshlst list --tag docs --priority high --due-before 2026-07-01

The list output is compact and sortable:

000001 high 2026-06-30 todo Ship docs [#docs #release]

Tasks are sorted by due date first, then priority, then creation time.

Show a task

wshlst show write-project-readme
wshlst show 'task(000001)'
wshlst show .tasks/000001-write-project-readme.md

show prints the full Markdown file, including frontmatter and body.

Update a task

wshlst update write-project-readme --title "Write usage README"
wshlst update 'task(000001)' --body "# Notes\n\nKeep it concise."
wshlst update 'task(000001)' --file notes/replacement.md
wshlst update 'task(000001)' --link https://example.com/new-reference
wshlst update 'task(000001)' --tag docs --tag cli --priority normal --due 2026-07-05

Updating a title does not rename the task file. Content sources are mutually exclusive: use one of --body, --file, or --link per update.

Finish or archive

wshlst finish 'task(000001)'
wshlst rm write-project-readme

finish sets the task status to done and records finished_at. rm archives the task in place by setting the status to archived; it does not delete the Markdown file.

Task References

Commands that operate on an existing task accept:

• Slug: write-project-readme
• Explicit ID: task(000001)
• File path: .tasks/000001-write-project-readme.md

Bare numeric IDs are intentionally rejected, so use task(000001) when you want to reference a task by ID.

Development

Install dependencies:

uv sync --dev

Run the test suite:

uv run pytest

Run the CLI from the working tree:

uv run wshlst --help

License

No license file is currently included in this repository.