Metadata-Version: 2.4
Name: tsk-todo
Version: 0.1.0
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: Topic :: Utilities
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

A small task manager for the terminal.

```
$ tsk add water the plants @home +garden due:tomorrow every:weekly
added 1: water the plants

$ tsk add fix the login bug @work +urgent due:yesterday p:h
added 2: fix the login bug

$ tsk
2  H  yesterday  fix the login bug @work +urgent
1     tomorrow   water the plants @home +garden every:weekly
```

No daemon, no config file, no dependencies. Your tasks live in one JSON file you can read.

## Install

Needs Python 3.11 or newer.

```
git clone https://github.com/michaelrbarley/tsk-todo
cd tsk-todo
uv tool install .
```

The command is `tsk`. The package is `tsk-todo`, because `tsk` on PyPI belongs to something else.

Or run it from the clone without installing anything:

```
uv run tsk
```

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