Hooks

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

• Configuration
• Stages
• Debugging
• Examples
  • Shell

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)
}

During execution, a called hook should print a result 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
  …  // Other fields depending on hook type (check out table below)
}

Hooks can write to stderr at any time, but it's not recommended. Rather write a JSON object to stdout and let TaskLite print the message / warning / error with improved formatting and coloring.

{ message: "…", … }

{ message: "…", … }

{ arguments: […] }

{ message: "…", … }

{ message: "…", … }

{
  arguments: […],
  taskToAdd: {}
}
      

{
  taskToAdd: {},
  message: "…",
  …,
}
      

{ message: "…", … }

{
  arguments: […],
  taskAdded: {}
}
      

{
  taskAdded: {},
  message: "…",
  …
}
      

{ message: "…", … }

{
  arguments: […],
  taskOriginal: {}
}
      

{
  taskToModify: {},
  message: "…",
  …
}
      

{ message: "…", … }

{
  arguments: […],
  taskOriginal: {},
  taskModified: {}
}
      

{
  taskModified: {},
  message: "…",
  …
}
      

{ message: "…", … }

❌

{ message: "…", … }

{ message: "…", … }

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 "{}"