Metadata-Version: 2.4
Name: wshlst
Version: 0.1.0
Summary: wshlst is a simple task manager CLI
Author-email: Cesar Cardoso <hello@cesarcardoso.cc>
License-Expression: MIT
Project-URL: Repository, https://github.com/bouli/wshlst
Project-URL: Changelog, https://github.com/bouli/wshlst/releases/latest
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0.2

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

```bash
uv sync
uv run wshlst --help
```

You can also install it into your current Python environment:

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

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

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

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

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

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

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

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

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

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

```bash
uv sync --dev
```

Run the test suite:

```bash
uv run pytest
```

Run the CLI from the working tree:

```bash
uv run wshlst --help
```

## License

No license file is currently included in this repository.
