Skip to main content

wshlst v0.1.1

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.

Metadata

Release files for wshlst 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wshlst 0.1.1
File Size Uploaded Provenance Actions
wshlst-0.1.1.tar.gz 15.6 kB With provenance Details for wshlst-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wshlst 0.1.1
File Interpreter ABI Platform Actions
wshlst-0.1.1-py3-none-any.whl Python 3 none any Details for wshlst-0.1.1-py3-none-any.whl

Total release size: 25.1 kB

Release files / wshlst-0.1.1.tar.gz

Download URL wshlst-0.1.1.tar.gz
Size 15.6 kB
Tags Source
SHA-256 checksum
How to use checksums
3783b824b0fc1eaaca8442131900677e23bd8a7d1045ccccc52b2b4c0f89aedf
BLAKE2b-256 checksum
How to use checksums
dc792dec9deaa2c9173a51763b1988b96d4b2f6e5e12cae1116ba967b1e7d112
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Release files / wshlst-0.1.1-py3-none-any.whl

Download URL wshlst-0.1.1-py3-none-any.whl
Size 9.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
68a7d3633f8c9387c1e415f384ea1fc849db1e804eead5364c41f291921761cb
BLAKE2b-256 checksum
How to use checksums
a9dee4e1f7fffa10acc0086b701d07be6fdbb58d7f9387d94d8c14caec21ccc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

Security for wshlst 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wshlst-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page