Koi fish

Command line task runner & automation tool

How to use

• Describe tasks as tables/dictionaries in a config file named 'koi.toml'.

[test]
description = "run tests"
pre_run = "uv sync --all-extras --dev"
commands = "uv run pytest -v ."
post_run = "rm -rf .pytest_cache/"

• description, pre_run and post_run could be optional but not commands
• post_run always runs as cleanup (even if pre_run or commands failed)

[no-deps]
commands = "echo 'Hello world'"

• they can have long (full) or short names

[test]
info = "run tests"
pre = "uv sync --all-extras --dev"
cmd = "uv run pytest -v ."
post = "rm -rf .pytest_cache/"

• pre_run, commands and post_run could be strings or (in case of more than one) a list of strings

commands = ["uv run ruff check", "uv run ruff format"]

• Optional [params] table: define reusable values and reference them with the @@ prefix

[params]
flag = "dev"
fmt = "format"

[install]
commands = "uv sync --all-extras --@@flag"

[format]
commands = ["uv run ruff check", "uv run ruff @@fmt"]

• You could provide an optional [run] table inside the config file with a 'main' flow - list of selected tasks to run, alongside with other flows
  (In this case the 'main' table is mandatory and will be executed by default unless explicitly specified otherwise)

[run]
main = ["lint", "format", "test"]
full = ["install", "lint", "format", "test", "teardown"]

Example koi.toml (used as a main automation tool during the development of this project)

[params]
flag = "dev"
fmt = "format"

[install]
description = "setup .venv and install dependencies"
commands = "uv sync --all-extras --@@flag"

[format]
description = "format code"
commands = ["uv run ruff check", "uv run ruff @@fmt"]

[lint]
description = "run mypy"
commands = "uv run mypy ."

[teardown]
description = "remove venv and cache"
commands = "rm -rf .venv/ .ruff_cache/ .mypy_cache/"

[run]
description = "tasks pipeline"
main = ["install", "format", "lint"]

• Run the tool in the terminal with a simple 'koi' command and pass the directory path where the koi.toml file resides
  (if it is the current directory the path argument can be omitted)

$ koi ~/pyproj/foo/

(logs omitted...)
$ All tasks succeeded! ['lint', 'format', 'test']
Run took: 14.088007061000098

• In case of failing tasks you get general stats

(logs omitted...)
$ Unsuccessful run took: 13.532951637999759
Failed tasks: ['format']
Successful tasks: ['lint', 'test']

or

$ Unsuccessful run took: 8.48367640699962
Failed tasks: ['format']
Successful tasks: ['lint']
Skipped tasks: ['test']

Running 'koi <path>' executes the 'main' flow from the [run] table.
If no such table is present, koi_fish will execute all tasks specified in the config file

• You could run specific tasks in the command line

$ koi --task format

or a list of tasks

$ koi -t format test

NB: If there is a 'run' table in the config file tasks specified in the command line take precedence

• other available options

# run all tasks from the config file
$ koi --run-all  # short form: -r

# hide output logs from running commands
$ koi --silent  # -s

# don't print shell commands - similar to @<command> in Makefile
$ koi --mute-commands  # -m

# skip task(s) from config file - can be combined e.g. with --run-all
$ koi -r --skip test  # -S

# cancel flow if a task fails
$ koi --fail-fast  # -F

# task(s) to run at the end if the flow fails
$ koi -rF --finally teardown

# allow duplicate tasks in flow
$ koi --allow-duplicates  # -A

# disable colored output in logs
$ koi --no-color  # -n

# run task(s) from given 'flow' table
$ koi --flow bar  # -f

• commands showing data

# display all tasks from the config file
$ koi --all  # -a
# ['install', 'format', 'test', 'teardown', 'run']

# display 'run' table
$ koi --config  # -c

# display all tasks from a flow inside 'run' table
$ koi --describe-flow main # -D
# ['install', 'format', 'test']

# display config for given task(s)
$ koi --describe format  # -d
# FORMAT
#         description: format code
#         commands:    uv run ruff check
#                      uv run ruff format