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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.