mdtasks

Simple commandline tasks and tickets via markdown files

Installation

uv tool install mdtasks

The tool installs an executable mdtasks and an alias t that refers to the same executable.

Usage

Use t --help for detailed up to date help.

Tasks are stored in a central folder by can be grouped by project and context. Typically, you will have one or two projects but separate contexts (e.g. "messaging", "backend", "ux", "website", ...). You can set both via environment variables. Use direnv to automatically switch based on the current directory. The following env vars are read:

To create your first task, run

t new my-first-task --use-full-spec

This will scaffold a task, open your preferred editor ($EDITOR) to let you edit the task and will then move the tasks to $MDTASKS_ROOT/open/ directory. The flag --use-full-spec is useful while you're not yet really familiar with mdtasks metadata schema: when called with --use-full-spec, mdtasks will add the full metadata schema to the task file, including optional arguments.

To see an overview of existing tasks, run

t ls

For other kinds of usage, use t --help.

Projects vs Contexts

Projects and contexts may appear quite similar, but they aren't really: Typically, projects refer to an overarching concept. You work on that project for a longer time. That's why mdtasks isn't really able to filter by project from the command line. The idea is that you might have projects "private" and "work". You can filter by project only via environment variables (e.g. by setting MDTASKS_PROJECT for a particular directory via direnv). On the other hand, contexts are less tightly coupled to a particular directory and the cli typically allows for ad-hoc switches between different contexts (although you can also set the default context via environment variable).

Versioning

We strictly use semantic versioning. Don't be fooled by the 1.x major version. THis isn't necessarily super stable software. However, we strictly increase version numbers on every breaking change.