Hooks

Hooks are scripts that can be executed at various stages of TaskLite's execution.

Configuration

Hooks can either be specified via the config file or via hook files.

If the files have an extension (e.g. post-add.lua) the corresponding interpreter will be used. Otherwise the file will be executed as a shell script. Currently supported interpreters are: lua, python3, ruby, node.

If the hook files are shell scripts, they must be executable (chmod +x). Otherwise they can't be executed directly by TaskLite.

It's recommended to use Lua for hooks as it's simple, lightweight, and has the best performance. Futhermore, future versions of TaskLite will include a Lua interpreter for even better performance.

Stages

Following stages are available:

  • Launch
    • pre-launch - After reading all configs, but before any TaskLite code is executed. Can be used to prevent execution of TaskLite.
    • post-launch - After reading CLI arguments, setting up the database and running all migrations.
  • Add
    • pre-add - Right before adding a new task. Can be used to prevent addition of task.
    • post-add - After new task was added.
  • Modify
    • pre-modify - Right before a task gets modified. Can be used to prevent modification of task.
    • post-modify - After task was modified.
  • Exit
    • pre-exit - Pre printing results
    • post-exit - Last thing before program termination

The hooks receive JSON data from TaskLite via stdin. We're using JSON5 here for better readability.

Included fields are:

{
  arguments: […],  // Command line arguments (after `tasklite`)
  …  // Stage specific fields (see below)
}

After execution, a called hook can print a JSON object to stdout. All fields of the JSON are optional.

Possible values:

{
  message: "…",  // A message to display on stdout
  warning: "…",  // A warning to display on stderr
  error: "…",  // An error to display on stderr
  …  // Any other fields you want to include
}

Hooks can write to stdout at any time, but it's not recommended. Rather write a { message: "…" } object to stdout and let TaskLite print the message with improved formatting and coloring. Same goes for stderr.

Event Stdin Stdout on Success
(exitcode == 0)		 Stdout on Error
(exitcode != 0)
pre‑launch ❌ 
{ message: "…", … }
 
{ message: "…", … }
Processing terminates
post‑launch 
{ arguments: […] }
 
{ message: "…", … }
 
{ message: "…", … }
Processing terminates
pre‑add 
{
  arguments: […],
  taskToAdd: {}
}
      
{
  taskToAdd: {},
  message: "…",
  …,
}
      
{ message: "…", … }
Processing terminates
post‑add 
{
  arguments: […],
  taskAdded: {}
}
      
{ message: "…", … }
 
{ message: "…", … }
Processing terminates
pre‑modify 
{
  arguments: […],
  taskOriginal: {}
}
      
{
  taskModified: {},
  message: "…",
  …
}
      
{ message: "…", … }
Processing terminates
post‑modify 
{
  arguments: […],
  taskOriginal: {},
  taskModified: {}
}
      
{
  taskModified: {},
  message: "…",
  …
}
      
{ message: "…", … }
Processing terminates
pre‑exit 
❌
 
{ message: "…", … }
 
{ message: "…", … }
Processing terminates
post‑exit 
❌
 
{ message: "…", … }
 
{ message: "…", … }
Processing terminates

Debugging

To see the JSON for a single task run:

tl ndjson | grep $ULID_OF_TASK | head -n 1 | jq

Examples

Shell

Pre launch:

stdin=$(cat)

>&2 echo "File > pre-launch: Input via stdin:"
>&2 echo "$stdin"
echo "{}"

Post launch:

stdin=$(cat)

>&2 echo "File > post-launch: Input via stdin:"
>&2 echo "$stdin"
echo "{}"

Pre add:

stdin=$(cat)

>&2 echo "File > pre-add: Input via stdin:"
>&2 echo "$stdin"
echo "{}"