taskninja v0.1.0-alpha.2

taskninja

A CLI tool to parse tasks and worklogs out of Markdown documents and print them to standard output, either in tabular of CSV format. Supports sorting, filtering and tag-based metadata.

Introduction

See the post on the rationale behind taskninja on my blog.

Status

Alpha software, though you could consider it a bootstrapped task management app in that I use taskninja to manage its own development. Feedback from others would be invaluable to further shape its evolution.

Example

Given directory /foo/bar with a 20241010-baz.md file having the following contents:

## Todos

- [ ] a pending task
- [X] a completed task

taskninja will output the following:

$ taskninja /foo/bar

text             | done  | file            | date
---              | ---   | ---             | ---
a pending task   | false | 20241010-baz.md | 20241010
a completed task | true  | 20241010-baz.md | 20241010

Install

npm i -g taskninja

Usage

$ taskninja -h
usage: taskninja [-h] [-t TAGS] [-f FILTER] [-s SORT] [-w] [-W] [--csv] path

A CLI tool to parse, sort and filter tasks and worklogs out of Markdown documents and print them to standard output, either in tabular of CSV format.

positional arguments:
  path                  working directory

optional arguments:
  -h, --help            show this help message and exit
  -t TAGS, --tags TAGS  comma-separated list of tags to show
  -f FILTER, --filter FILTER
                        filtering expression such as: foo(=bar)
  -s SORT, --sort SORT  sorting expression such as: foo(asc)
  -w, --watch           enable watch mode
  -W, --worklogs        enable worklogs mode
  --csv                 enable CSV mode

Tags

taskninja uses the concept of tags as the unit of information that is used to describe both tasks and workflows.

Choosing which tags to show

The -t flag may be used to change which tags are displayed:

$ taskninja -t text,project,client,file,date /foo/bar

Autogenerated tags

taskninja auto-generates the following tags:

Inline tags

Tasks may be tagged inline:

- [ ] a pending task #project(foo) #client(bar)
- [X] a completed task

$ taskninja -t text,project,client,file,date /foo/bar

text                                      | project | client | file            | date
---                                       | ---     | ---    | ---             | ---
a pending task #project(foo) #client(bar) | foo     | bar    | 20241010-foo.md | 20241010
a completed task                          |         |        | 20241010-foo.md | 20241010

Tags may also be added after a line break (three consecutive spaces) so that they are not counted as part of the autogenerated text tag:

- [ ] a pending task   
      #project(foo) #client(bar)
- [X] a completed task

$ taskninja -t text,project,client,file,date /foo/bar

text             | project | client | file            | date
---              | ---     | ---    | ---             | ---
a pending task   | foo     | bar    | 20241010-foo.md | 20241010
a completed task |         |        | 20241010-foo.md | 20241010

Frontmatter tags

Tags will also be inherited from any YAML front-matter:

---
project: foo
client: bar
---

- [ ] a pending task
- [X] a completed task

taskninja will produce:

$ taskninja -t text,project,client,file,date /foo/bar

text             | project | client | file            | date
---              | ---     | ---    | ---             | ---
a pending task   | foo     | bar    | 20241010-foo.md | 20241010
a completed task | foo     | bar    | 20241010-foo.md | 20241010

Filtering by tag

taskninja accepts filter expression via the -f argument:

$ taskninja -f "client(=foo)" /foo/bar

Filtering syntax is as follows:

foo(isnull)      matches tasks without tag "foo"
foo(notnull)     matches tasks with tag "foo"
foo(=bar)        matches tasks with tag "foo" set to "bar"
foo(!=bar)       matches tasks with tag "foo" set to anything other than "bar"
foo(^=bar)       matches tasks with tag "foo" starting with "bar"
foo($=bar)       matches tasks with tag "foo" ending with "bar"
foo(*=bar*)      matches tasks with tag "foo" matching the pattern "bar*"

Filtering expressions can be combined:

foo(=bar),foo(!=baz)

Sorting by tag

taskninja accepts sorting expressions via the -s argument:

$ taskninja -s "client(asc)" /foo/bar

Sorting syntax is as follows:

foo(asc)      sorts tasks by the "foo" tag in ascending lexicographical order
foo(desc)     sorts tasks by the "foo" tag in descending lexicographical order

Sorting expressions can be combined for nested sorting:

foo(asc),bar(desc)

License

Released under the LGPL v3.0 (LGPL-3.0-only) license. See LICENSE.md.