<div id="readme"></div>
<div id="top"></div>
<div align="center">
<h1>
kindly 💖
<br>
<font size="4"><i>A nice little task runner</i></font>
</h1>
<font color="#848484" size="6">
[](https://hexdocs.pm/kindly/)
[](https://github.com/tynanbe/kindly/blob/main/LICENSE)
[](https://github.com/tynanbe/kindly/actions)
•
[](https://hex.pm/packages/kindly)
[](https://npmjs.com/package/@tynanbe/kindly)
[](https://jsr.io/@tynanbe/kindly)
<br>
[](https://gleam.run/)
[](https://www.typescriptlang.org/)
[](https://ecma-international.org/publications-and-standards/standards/ecma-262/)
•
[](https://nodejs.org/)
[](https://deno.com/)
[](https://bun.sh/)
<br>
[](https://github.com/tynanbe/kindly)
</font>
<font color="#848484">
### [Quickstart](https://hexdocs.pm/kindly/quickstart.html) • [API Reference](https://hexdocs.pm/kindly/kindly.html) • [Examples](https://hexdocs.pm/kindly/examples.html)
</font>
[<font color="#848484" size="6">• • •</font>](https://youtu.be/aaj08tCfsVw)
</div>
<div id="table-of-contents"></div>
<div id="toc"></div>
## Table of Contents
1. [Features](#features)
1. [Example](#example)
1. [About](#about)
1. [Try It](#try-it)
1. [Installation](#installation)
1. [Run It](#run-it)
1. [Completions](#completions)
1. [Where Next?](#where-next)
1. [Support](#support)
<div id="features"></div>
## Features
- Simple CLI and API
- Shell completions
- Declarative and functional
- Works with Gleam, TypeScript, and JavaScript
- Runs with Node.js, Deno, or Bun
<div id="example"></div>
## Example
<details open>
<summary><strong>Gleam</strong></summary>
```gleam
// dev/handbook.gleam
import kindly.{type Handbook, task}
pub fn main() -> Handbook {
kindly.handbook(for: "example")
|> task(
doc: "Format source code",
tags: ["format"],
action: kindly.just(run: "gleam", with: ["format"]),
)
|> task(
doc: "Check source code formatting",
tags: ["format-check", "check", "ci"],
action: kindly.just(run: "gleam", with: ["format", "--check"]),
)
}
```
</details>
<details>
<summary><strong>TypeScript & JavaScript</strong></summary>
```typescript
// handbook.ts, handbook.mjs, or handbook.js
import kindly from "jsr:@tynanbe/kindly";
export default kindly.handbook({ for: "example" })
.task({
doc: "Format source code",
tags: ["format"],
action: kindly.just("deno", "fmt"),
})
.task({
doc: "Check source code formatting",
tags: ["format-check", "check", "ci"],
action: kindly.just("deno", "fmt", "--check"),
});
```
</details>
<div id="about"></div>
## About
Kindly provides a simple yet flexible way to reference and run one or more
user-defined tasks specific to your project.
By creating a project Handbook with minimal boilerplate, you can write your
tasks in Gleam, TypeScript, or JavaScript for a better developer experience that
can also make it easier to ensure your tasks will work in any environment with
your runtime of choice (Node.js, Deno, or Bun).
Kindly bases task selection on a flat system of tags, although you could use it
to emulate a command tree typical of other CLI tools. This allows you to group
multiple tasks in a way that fits your project's needs and run all of them
together or filter selected tasks for those in the group.
For example, suppose your Handbook has tasks with the following tags:
```txt
A. test, erlang
B. test, javascript
C. format-check, gleam
D. format-check, erlang
E. format-check, javascript
```
Invoking Kindly with different arguments would run various tasks as follows
(_Note: You can always include the `--help` flag to show which tasks Kindly
plans to run given your other arguments_):
```sh
kindly test erlang # A
kindly test # A, B
kindly javascript # B, E
kindly format-check --any gleam erlang # C, D
```
The first tag for each task should be the most specific way to reference that
task. It's given special consideration in Kindly's help output.
### When to consider Kindly
Kindly is for projects whose tasks are starting to outgrow a flat list of
scripts.
Some handbooks use mostly direct task names. Others use grouped tasks, where one
tag names the broader work and additional tags narrow it down. Kindly does not
force one style. It is meant to support whichever shape fits the project and the
way people actually use it.
It's an attractive option when tasks overlap, share helpers, or are easier to
generate than hand-write. In those cases, composable task selection can be more
useful than inventing a separate command name for every path through the task
menu.
If your project only needs a few isolated commands, scripts may be simpler. If
your tasks are related, grouped, or better expressed as code, Kindly may be a
nice fit.
<div id="try-it"></div>
## Try It
<details open>
<summary><strong>Gleam</strong></summary>
```sh
# Add kindly to your Gleam project’s dev dependencies
gleam add --dev kindly
# Print help info
gleam run --module kindly
# Run an example task
gleam run -m kindly -- format-check
```
</details>
<details>
<summary><strong>Bun</strong></summary>
```sh
# Print help info
bunx --bun @tynanbe/kindly
# Run an example task
bunx --bun @tynanbe/kindly format-check
```
</details>
<details>
<summary><strong>Deno</strong></summary>
```sh
# Print help info
deno run --allow-all --reload jsr:@tynanbe/kindly
# Run an example task
deno run -Ar jsr:@tynanbe/kindly format-check
```
</details>
<details>
<summary><strong>Node.js</strong></summary>
```sh
# Print help info
npx @tynanbe/kindly
# Run an example task
npx @tynanbe/kindly format-check
```
</details>
> **Note:** If your project uses a `handbook.gleam` or `handbook.ts` module and
> you want to run it with Node.js, it's recommended to run Node.js v24.0+, for
> [type stripping](https://nodejs.org/api/typescript.html#type-stripping)
> support.
<div id="installation"></div>
## Installation
It's recommended to install Kindly globally with Deno, Bun, or your Node.js
package manager of choice. This method is the simplest way to get shell
completions, and Kindly will still run your handbook using your project's local
Kindly dependency.
<details>
<summary><strong>Bun</strong></summary>
```sh
bun install --global @tynanbe/kindly
```
</details>
<details open>
<summary><strong>Deno</strong></summary>
```sh
deno install --global --allow-all jsr:@tynanbe/kindly
```
</details>
<details>
<summary><strong>Node.js</strong></summary>
```sh
# Or similar for pnpm, yarn, etc.
npm install --global @tynanbe/kindly
```
</details>
<div id="run-it"></div>
## Run It
```sh
# Print help info
kindly
# Run an example task
kindly format-check
```
> **Note:** If your project uses a `handbook.gleam` or `handbook.ts` module and
> you want to run it with Node.js, it's recommended to run Node.js v24.0+, for
> [type stripping](https://nodejs.org/api/typescript.html#type-stripping)
> support.
<div id="completions"></div>
## Completions
After you've installed Kindly globally or worked out some other way to get
`kindly` on your `$PATH`, you can set up shell completions and Kindly will
suggest the tags for your project as well as its own flags.
<details>
<summary><strong>Bash</strong></summary>
```sh
# ~/.bashrc
if type kindly >/dev/null 2>&1; then
eval "$(kindly --cue bash)"
fi
```
</details>
<details open>
<summary><strong>Fish</strong></summary>
```sh
# ~/.config/fish/config.fish
if type kindly >/dev/null 2>&1
kindly --cue fish | source
end
```
</details>
<details>
<summary><strong>PowerShell (pwsh)</strong></summary>
```sh
# ~/.config/powershell/profile.ps1
# or $HOME\Documents\PowerShell\profile.ps1
if (Get-Command -Name kindly -ErrorAction Ignore) {
kindly --cue pwsh | Out-String | Invoke-Expression
}
# -Function MenuComplete is recommended, but
# -Function Complete should also work
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
```
</details>
<details>
<summary><strong>Zsh</strong></summary>
```sh
# ~/.zshrc
if type kindly >/dev/null 2>&1; then
eval "$(kindly --cue zsh)"
fi
```
</details>
<div id="where-next"></div>
## Where Next?
[Quickstart](https://hexdocs.pm/kindly/quickstart.html)
[API Reference](https://hexdocs.pm/kindly/kindly.html)
[Examples](https://hexdocs.pm/kindly/examples.html)
<div id="support"></div>
## Support
Contributions are welcome. Feel free to
[open an issue](https://github.com/tynanbe/kindly/issues) on GitHub to suggest a
feature or report a bug.
If your project uses Kindly, you may wish to add a badge to your `README`.
<details>
<summary><strong>Kindly Badge Markdown</strong></summary>
```md
[](https://github.com/tynanbe/kindly)
```
</details>
<div align="center">
[](https://github.com/tynanbe/kindly)
</div>
