NAME
tasq - summarise tasks from Markdown files
SYNOPSIS
tasq [--config PATH] [--files GLOB]... [VIEW or SQL_QUERY]...
DESCRIPTION
This program gathers task lists from Markdown files, producing
customisable summaries using SQL queries on them.
This allows keeping track of tasks globally while keeping related
ideas, notes and tasks grouped together in text files.
By default, it produces a short summary of currently actionable
tasks.
“tasq” is a portmanteau word combining “task” and “query”. Order,
order!
VIEWS AND QUERIES
The following default views are available:
$ tasq unscheduled- Lists all pending tasks without a scheduled date, with earliest due
dates and highest priorities first. This provides a summary of tasks
which are yet to be scheduled.
$ tasq scheduled- Lists all pending tasks having a scheduled date, with earliest
scheduled dates and highest priorities first. This provides an
agenda of planned tasks.
$ tasq postponed- Lists all pending tasks scheduled for tomorrow and beyond, with
earliest scheduled dates and highest priorities first. This provides
an agenda of planned tasks which are not actionable yet.
$ tasq current- Lists all pending tasks with scheduled dates which are either
missed, planned for today, or upcoming tomorrow, with earliest
scheduled or due dates first, and highest priorities first. This
provides an immediate program of actionable tasks.
Custom summaries can be produced using SQL queries on the virtual
“tasks” table. The available columns are:
| Column | Description |
|---|
filepath | Path to the file in which the task is defined. |
line | Line number at which the task is defined within its file. |
done | Whether the task is marked as done. |
subject | The free-form text subject of the task. |
tags | List of tags associated with the task. |
priority | The integer priority of the task. |
due | The due date (with optional time) of the task. |
scheduled | The scheduled date (with optional time) of the task. |
Here is an example of custom query counting the pending tasks
with missed deadlines in each note file:
$ tasq "select basename(filepath), count(*) from tasks
where not done and due.date < current_date()
group by filepath"
View rows can be colourised through the optional
_color column. The following colours are rendered:
white, black, grey,
darkgrey, red, darkred,
green, darkgreen, yellow,
darkyellow, blue, darkblue,
magenta, darkmagenta, cyan,
darkcyan.
MARKDOWN TASKS
Tasks are list items having a checkbox. Each has a subject, which
may contain hashtags (#tag), and optional
key:value attributes:
priority:<INTEGER or KEYWORD>- The priority of the task. Higher means more urgent. The following
literals can also be used: “low” (-1), “medium” (0), “high” (7),
“urgent” (9). The default priority is 0. Aliases for this key:
prio, pri. due:<DATE or DATETIME>- The date and time for which the task is due. Accepted format: ISO
8601 date and time, with delimiters and right-most components all
optional. Aliases for this key:
for,
deadline. scheduled:<DATE or DATETIME>- The date and time at which the task is planned to be started,
Accepted format: ISO 8601 date and time, with delimiters and
right-most components all optional. Aliases for this key:
sched, planned, start,
on, postponed, wait.
Task data are specified in-line or in non-task list items
directly within them.
Hashtags and attributes in section titles and outer list items
(task and non-task) are propagated to the tasks within them. The
attribute value specified last takes precedence.
Here’s an example Markdown snippet containing two tasks; both
tagged with “tasq” and having a common due date; the first marked as
done, with a scheduled date and a priority; the second still
pending, with a scheduled date and time:
# Some work on #tasq
* due:2025-06-15
* [x] on:2025-06-14 pri:1 Write a manual page
* [ ] Whip a new release into shape
* on:2025-06-15T15:00
This produces in the following entries in tasq:
| Done | Scheduled | Due | Prio | Subject | Tags |
|---|
| yes | 06-14 | 06-15 | 1 | Write a manual page | tasq |
| no | 06-15 15:00 | 06-15 | | Whip a new release into shape | tasq |
COMMAND OPTIONS
<VIEW_NAME or SQL_QUERY>- View name or SQL query on the “tasks” table. Can be specified
multiple times. Default:
select * from current limit 25. -c, --config <CONFIG_PATH>- Path to the configuration file to use. Default:
($XDG_CONFIG_HOME:$XDG_CONFIG_DIRS)/tasq/tasq.toml -f, --files <GLOB_PATTERN>- Glob pattern of source Markdown files. Can be specified multiple
times. Default:
~/documents/**/*.md -o, --output <FORMAT>- Output format. Either
table or jsonl.
Default: table. -h, --help- Print help message.
-V, --version- Print version info.
CONFIGURATION FILE
This program can be configured with a TOML file located at
$XDG_CONFIG_DIRS/tasq/tasq.toml.
The following configuration keys are accepted:
file_patterns- Glob patterns of source Markdown files, used when no location is
supplied to the command. Default:
[ "~/documents/**/*.md" ] output- Output format. Either
table or jsonl.
Default: table. setup- Custom setup SQL statements. Useful to save user-defined views from
queries on the “tasks” table.
default_queries- List of view names or SQL queries on the “tasks” table, used when no
query is supplied to the command.
SOURCE CODE AND PACKAGES
The source code repository is located at
https://src.euxane.eu/tasq.
Contributions are welcomed. Issues and patches should be emailed
to the author of the program.
A list of distribution packages is available at
https://repology.org/project/tasq.
The latest development version can be compiled and run using Nix
with:
nix run git+https://src.euxane.eu/tasq -- --help.
LICENCE AND COPYRIGHT
Copyright (C) 2025 Euxane TRAN-GIRARD.
This program is published under the terms of the European Union
Public Licence, version 1.2. (See the included
licence.txt).