koi-fish 1.0.2

CLI task runner & automation tool

Koi fish

Command line task runner & automation tool

---

How to use

• Describe jobs as tables/dictionaries in a config file called 'koi.toml'.
  (Put the config inside the root directory of your project)

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

• description, dependencies and cleanup could be optional but not commands

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

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

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

• You could provide a [run] table inside the config file with a 'suite' - list of selected jobs to run

[run]
suite = ["lint", "format", "test"]

---

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

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

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

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

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

[run]
description = "jobs pipeline"
suite = ["install", "format", "lint"]

---

• Run the tool in the terminal with a simple 'koi' command

$ koi

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

• In case of failing jobs you get general stats

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

or

$ Unsuccessful detoxing took: 8.48367640699962
Failed jobs: ['format']
Successful jobs: ['lint']
Skipped jobs: ['test']

---

• You could run specific jobs in the command line

$ koi --job format

or a list of jobs

$ koi -j format test

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

• other available options

# run all jobs 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 a job from config file - can be combined e.g. with --run-all
$ koi -r --skip test

• commands showing data

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

# display all jobs from the 'suite' table
$ koi --suite  # -t
# ['install', 'format', 'test']

# display config for a given job
$ koi --describe  format  # -d
# FORMAT
#         description: format code
#         commands: uv run ruff check
#                   uv run ruff format