Metadata-Version: 2.4
Name: tsk-todo
Version: 0.1.2
Summary: Minimal todo CLI for the terminal. Pure Python, zero dependencies.
Keywords: cli,todo,task,task-manager,productivity,terminal,gtd
Author: michaelrbarley
Author-email: michaelrbarley <301309661+michaelrbarley@users.noreply.github.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/michaelrbarley/tsk-todo
Project-URL: Source, https://github.com/michaelrbarley/tsk-todo
Project-URL: Issues, https://github.com/michaelrbarley/tsk-todo/issues
Description-Content-Type: text/markdown

# tsk

[![PyPI](https://img.shields.io/pypi/v/tsk-todo)](https://pypi.org/project/tsk-todo/)
[![Python](https://img.shields.io/pypi/pyversions/tsk-todo)](https://pypi.org/project/tsk-todo/)
[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](https://pypi.org/project/tsk-todo/)

A small task manager for the terminal. One line to add a task, one file to keep them in, and
nothing to configure.

![tsk adding three tasks, listing them, and completing a repeating one](https://github.com/michaelrbarley/tsk-todo/raw/master/docs/demo.svg)

```
uv tool install tsk-todo
```

Or try it without installing anything: `uvx --from tsk-todo tsk`

## Why you might like it

**There is nothing to set up.** No config file, no theme to pick, no coefficients to tune. It works
the way it works, and the first thing you do with it is add a task.

**You can predict the order.** Due date, then priority, then id. That is the entire rule. Nothing
computes a score behind your back, so a task never jumps the queue for a reason you cannot see.

**It repeats properly.** Finish a daily task a week late and the next one is due tomorrow, not eight
overdue copies waiting to be dismissed one at a time.

**It stays out of the way.** `tsk add email bob@example.com about the invoice` does exactly what you
meant. So does `tsk add fix the -v flag`. Nothing gets swallowed as metadata.

**You can leave whenever.** Your tasks are one JSON file you can read, diff and commit. Stop using
`tsk` tomorrow and they are still sitting there in a format anything can open.

## Install

Needs Python 3.11 or newer, and nothing else. There are no runtime dependencies.

```
uv tool install tsk-todo
```

The command is `tsk`. The package is [`tsk-todo`](https://pypi.org/project/tsk-todo/), because
`tsk` on PyPI belongs to something else. `pip install tsk-todo` works too, and from a clone it is
`uv tool install .`

## The idea

You type what you mean and `tsk` works out which parts are metadata:

```
tsk add renew the passport @admin +boring due:eom p:h
```

`@admin` is the project, `+boring` is a tag, `due:eom` is the end of this month, `p:h` is high
priority. Everything left over is the task itself.

Only `due:`, `p:` and `every:` are read as attributes, so ordinary text stays ordinary:

```
$ tsk add email bob@example.com about the invoice
$ tsk add fix the -v flag
$ tsk add ticket: replace the boiler
```

None of those pick up a project, a tag or an attribute. If it is not a form `tsk` knows, it is
part of the description.

## Commands

```
tsk                        list pending tasks
tsk add <text> [attrs]     add a task
tsk done <id>...           complete tasks
tsk rm <id>...             delete tasks
tsk edit <id> <attrs>      change a task
tsk note <id> <text>       attach a note
tsk show <id>              show one task in full
tsk list [filters]         list tasks
```

`tsk 3` on its own is shorthand for `tsk show 3`.

`done` and `rm` take several ids at once: `tsk done 2 5 9`.

## Attributes

Use these when adding or editing.

```
@project      set the project
+tag          add a tag
-tag          remove a tag, when editing
due:<when>    set a due date
p:h|m|l       set priority, high medium or low
every:<how>   reschedule on completion
```

Priority also accepts the full word, so `p:high` and `p:h` are the same.

Editing changes only what you name. Everything else is left alone.

```
$ tsk edit 3 due:friday +urgent
updated 3: read the book
```

To clear something, give it no value:

```
$ tsk edit 3 due: p: every:
```

A bare `@` clears the project. A leading `-` removes a tag.

## Filters

```
tsk +garden              tagged garden
tsk -work                not tagged work
tsk @home                in the home project
tsk overdue              past due
tsk due:friday           due on or before friday
tsk done                 completed tasks
tsk all                  everything
tsk plants               search descriptions and notes
```

Filters combine, and `list` is optional:

```
$ tsk @home +garden overdue
$ tsk list @work due:eow
```

Bare words search. `tsk list dentist` finds anything with dentist in the description or in a note.

## Dates

Anywhere a date is wanted:

```
today, tomorrow, yesterday
monday .. sunday, or mon .. sun
3d, 2w, 1m, 1y
eow, eom, eoy
2026-08-01
```

Weekday names mean the next one coming. On a Thursday, `due:thursday` is a week away, not today.

Month and year offsets land on a real date. `1m` from the 31st of January is the 28th of February,
not the 3rd of March.

Due dates are plain calendar dates. `due:friday` means Friday wherever you happen to be, and it
does not drift when you cross a timezone.

## Repeats

```
every:daily
every:weekdays
every:weekly
every:monthly
every:yearly
```

A repeating task needs a due date. When you complete it, the next one is created for you:

```
$ tsk done 1
done 1: water the plants
  repeats as 5, due in 1 week
```

The next date is worked out from the old due date, then rolled forward until it is in the future.
Finish a daily task five days late and the next one is due tomorrow, not last week. You never come
back to a pile of overdue copies.

Notes do not carry over. The completed task keeps them.

## Notes

```
$ tsk note 3 the ferns look worse than the rest
noted on 3: water the plants
```

Tasks with notes are marked with a `*` in the list. `tsk show 3` prints them.

## Ordering

Tasks sort by due date, then priority, then id. That is the whole rule. Nothing is scored or
weighted behind your back, so the order is always one you can predict and explain.

Undated tasks sort last. They are not urgent, they are just there.

## Your data

One JSON file, at `~/.local/share/tsk/tasks.json` unless you say otherwise:

```json
{
  "version": 1,
  "issued": 7,
  "tasks": [
    {
      "id": 2,
      "description": "fix the login bug",
      "status": "pending",
      "created": "2026-07-16T14:49:48+00:00",
      "project": "work",
      "tags": ["urgent"],
      "due": "2026-07-15",
      "priority": "high"
    }
  ]
}
```

Set `TSK_DATA` to put it somewhere else, or `XDG_DATA_HOME` to move the lot. Keep it in a git repo
if you want history. Tags are written in a fixed order and absent fields are left out, so diffs
stay small.

Writes are atomic. The file is written beside itself and then moved into place, so an interrupted
write cannot leave you with half a file. Existing permissions are preserved.

Ids are never reused. Once id 3 has been handed out, no later task gets it, even if you delete task
3 the same day. The id you read a minute ago is still the task you thought it was.

## Colour

On when writing to a terminal, off when piped. Set `NO_COLOR` to turn it off entirely.

Overdue is red, due today is yellow, projects are cyan, tags are magenta.

## What it does not do

There is no urgency score, no dependency graph, no user defined attributes, no hooks, no custom
report definitions and no sync. Each of those either failed the question "would I miss this" or
costs far more than it returns for a tool this size.

If you want a task on the calendar, `due:` is where it goes. If you want to find it later, tag it.
That is most of task management.

## Development

```
uv sync
uv run pytest
uv run ruff check .
uv run ruff format .
uv run mypy
```

The suite runs in well under a second. It is worth keeping it that way.

## Licence

MIT
