run.sh: how we manage CLI tasks in imgproxy
In this post, we’ll explore how imgproxy manages CLI tasks using our home-brewed run.sh script. We’ll discuss the structure of the script, how it handles different tasks, and best practices for extending and maintaining it.
If you’re not interested in reading another team dissing Makefile and just want to know what we have to offer instead, you can jump right here.
The ecosystem we live in
Every project, more or less complex, over time, grows a set of recurring tasks: building, testing, linting, dependency updates, and so on. The more this set grows, the clearer the need becomes for a way to organize it.
Some ecosystems already have a standard, or nearly standard, way to run project tasks: npm scripts in Node.js, rake in Ruby, cargo make in Rust, and so on.
Go has nothing of the kind.
If the question “What tool should we use to organize recurring tasks?” were asked on Family Feud, the top answer would certainly be Makefile. But is it really the best choice?
Makefile is not a task runner
make has a clear advantage: it is widely available. As a developer, you most likely already have it on your machine; your CI environment almost certainly does, and so do your colleagues and contributors. This makes it an attractive choice for managing recurring tasks without introducing additional dependencies.
But it is not a task runner; it was designed primarily for build automation. For simple tasks, like running a one-liner command or a small script without arguments, Makefile works well. But as soon as you need a little bit more, make will make you (pun intended) jump through hoops.
Here are some examples of where we at imgproxy struggled with Makefile as a task runner.
No CLI arguments by design
Make simply doesn’t have any built-in support for CLI arguments. You can’t just do make target arg1 arg2 as you would with a typical CLI tool: everything you pass to make it interprets as a target. Of course, you can use variables to pass arguments, like make target ARG1=value1 ARG2=value2, but this is cumbersome and error-prone. Especially when the task requires those arguments on each run.
No task listing
Listing available tasks along with their descriptions is quite a nice feature to have in a task runner. Even project maintainers may forget the names of some tasks they use only occasionally, not to mention new contributors. With make, the only way to find the task you need is to read the Makefile itself.
Syntax that pretends to be shell
Though Makefile’s syntax looks like a shell script at first glance, it is not. This can be misleading and cause subtle bugs, especially for developers who are used to writing shell scripts.
For starters, make runs each command in a separate shell instance. This means that any changes to the environment, such as setting variables or changing directories, do not persist between commands.
Variable substitution also behaves differently than in a typical shell script. For example, FOO=bar; echo "FOO is set to ${FOO}" works in a shell script and prints FOO is set to bar. But make expands variables before executing the command, so what it actually runs is FOO=bar; echo "FOO is set to ". To get the expected result in a Makefile, use $${FOO}. This is quite easy to overlook.
.PHONY targets are a must
In a Makefile, you often need to declare targets as .PHONY to indicate that they are not actual files. Otherwise, if a file with the same name as the target exists, make may consider the target up-to-date and skip its execution, leading to unexpected behavior. This adds extra boilerplate, and it is one more thing one could easily forget.
More than that, it is a source of subtle bugs. Take a look at this Makefile:
.PHONY: lint-go
lint-go:
@echo "Running Go linter..."
.PHONY: lint-clang
ling-clang:
@echo "Running C linter..."
.PHONY: lint
lint: lint-go lint-clang Everything looks fine at first glance, but if you run make lint, you’ll see only Running Go linter.... The C linter won’t run because of the typo in the target name (ling-clang instead of lint-clang). But since there’s no typo in .PHONY: lint-clang, make won’t throw an error and will silently do nothing. Because of this exact bug, we had been skipping the C linter for months without even realizing it.
No “early exit”
In a Makefile, you can’t stop the execution of subsequent targets without throwing an error. Not a thing most users would care about, but sometimes it can be a real problem.
The task we needed this for is running commands in Docker. imgproxy has lots of dependencies, and running tests, linting, etc. in a consistent environment is crucial. Running commands in Docker ensures that the environment is always the same, regardless of the host system.
The idea was simple:
- Create a
_run-in-dockertarget that checks if theMakefileis being executed inside the Docker container. - If it is, do nothing and continue with the current Makefile execution.
- If it isn’t, run the command inside the Docker container and exit the current Makefile execution.
- Add
_run-in-dockeras a prerequisite to all targets that need to run inside Docker.
Despite all the simplicity, there’s one elephant in the room: “…and exit the current Makefile execution”, which is not possible with make. So we ended up with this:
.PHONY: _run-in-docker
_run-in-docker:
ifdef IMGPROXY_IN_BASE_CONTAINER
@$(MAKE) $(DOCKERCMD)
else
@docker compose -f "$(MAKEFILE_DIR)/.devcontainer/docker-compose.yml" \
run --rm -it imgproxy \
bash -c "make $(DOCKERCMD)"
endif
.PHONY: task _task
task: DOCKERCMD := _task
task: _run-in-docker
_task:
@echo "Running task..." So much ugly machinery for a simple thing just because we can’t exit early. To be honest, we know a couple more ways to solve this problem, but each comes with its own trade-offs, and none are much prettier.
What about alternatives?
The described make issues were long-standing pain points, which naturally led to the development of various task runners. Here are some alternatives we considered when we decided to get rid of Makefile:
- Just can be described as Make on steroids. It solves Make’s pain points and adds some useful features on top. But it is yet another binary to install and DSL to learn. Lack of official syntax highlighting plugins for editors is also a downside.
- Taskfile is readable YAML with watch mode and parallelism, but verbose, with YAML-in-YAML shell quoting and a runtime to install. It is written in Go and can be used via
go toolseamlessly (no separate installation step). However, typinggo tool task <task_name>every time is cumbersome. It looks nice for Go projects, and overall, we liked it most among the alternatives we tried. - Invoke is programmable, but needs Python and its environment just to run tasks.
- Mage uses plain Go functions as targets and is cross-platform, but needs Go installed, compiles the Magefile, and makes non-Go contributors read Go (not much of a problem for Go projects, though). Also, writing tasks that mostly run shell commands in Go isn’t much fun, but Mage does its best to reduce friction.
- argc is essentially the bash script preprocessor. It has a lightweight argument parser for bash scripts with useful macros, declarative arguments, and auto-generated help, but it’s still an additional dependency and not as widely adopted as plain bash.
And of course, you can just put a bunch of bash scripts in a bin directory and call them directly. bash is a dependency every developer has nowadays, after all. ls bin will show you all available tasks, but it won’t show their descriptions. And you have to implement usage info manually for each script.
But what if we want the simplicity of plain bash scripts, yet with some structure, task orchestration, useful helpers, and a consistent interface?
One script to rule them all
After exploring various task runners and being seduced by the simplicity of old, good bash scripts, we built what we believe takes the best of both worlds. Please welcome run.sh!
run.sh acts as an orchestrator for all project tasks, providing a consistent interface for executing the scripts and some tools to control their dependencies on each other, output helpers, and so forth.
It is written in pure bash, and the only required dependency is bash itself, version 3.2 or higher.
Installing the runner
Installation is as simple as downloading the script and making it executable. Just run this at your project root.
curl -fsSL https://raw.githubusercontent.com/imgproxy/run.sh/main/run -o run && chmod +x run The script lives in your project root, and you can run your project tasks by simply ./run <task>.
You can also install a global shell command for convenience:
./run install-global Global installation creates a function within .bashrc, .zshrc, or .config/fish/config.fish, depending on your current shell. The run script should still reside in your project root, but now you can omit the ./ prefix and run tasks using run <task> from anywhere within your project.
No other dependencies are required. To update your local run script, simply run the installation command again.
Task structure
A task is a bash script that can be executed via run.sh. Each task should be placed in a dedicated file under bin directory, and the file name corresponds to the task name. For example, a task named build would be defined in a file called bin/build.sh.
Typical task looks as follows:
#!/usr/bin/env bash
# Description for task list
description() { echo "Build the imgproxy binary"; }
# Help message for the task (`run help build`)
help() {
cat <<EOF
Usage: ./run $TASK_NAME [go-build-args...]
Builds the imgproxy binary. If -o is not passed via go-build-args, the
binary defaults to ./imgproxy.
Example:
./run build -o /tmp/imgproxy
EOF
}
# The task itself
main() {
run::require_tool go "go is required, see https://go.dev/doc/install"
go build -v -o imgproxy "$@" ./cli
} So, each script task must have three methods:
description– provides a short description of the task for the task list.help– displays detailed help information for the task.main– contains the actual implementation of the task.
CLI arguments are passed to the main function of the task. You can access them as in any other bash script or function: $@ for all arguments, $1, $2, etc. for individual arguments. You can parse them using standard bash techniques, such as getopts for option parsing. Or you can simply forward them to other commands or tasks.
List and help
To list available tasks, just run run:
$ run
run.sh — tasks in /Users/gzigzigzeo/go/imgproxy/bin (v0.0.1)
build-and-run Build the imgproxy binary, then run it (inside the base container)
build Build the imgproxy binary
bump-version Bump the imgproxy version in version.go and CHANGELOG.md
... To see the help message for a specific task, run run help <task>:
$ run help build
Usage: ./run build [go-build-args...]
Builds the imgproxy binary. If -o is not passed via go-build-args, the
binary defaults to ./imgproxy.
Example:
./run build -o /tmp/imgproxy Dependencies
Tasks can declare their dependencies on external tools and on each other. To check system dependencies, you can use the run::require_tool method:
main() {
run::require_tool go "go is required, see https://go.dev/doc/install"
# Do something with Go
} If a task depends on another task, you can use the run::depends_on method:
main() {
run::depends_on build test
# Do something after building and testing
} run::depends_on runs specified tasks without passing any arguments to them. If you need to pass arguments to a dependent task, you can use the run::invoke method instead:
main() {
run::invoke build -o /tmp/imgproxy
run::invoke launch /tmp/imgproxy
} Variables and helpers
In addition to providing structure for your tasks, run.sh aims to simplify their implementation by offering useful environment variables and helper functions.
run.sh sets the following environment variables:
PROJECT_ROOT— absolute path to the project root (the directory containing ./run). Useful when you need to build paths that don’t depend on the caller’s current working directory, e.g., “$PROJECT_ROOT/config/app.yml”.TASK_DIR— absolute path to the directory containing the tasks. Just in case you want to do something with the task files themselves.TASK_NAME— name of the task currently being invoked (bin/<name>.sh → <name>).
We mentioned run::require_tool, run::depends_on, and run::invoke helpers earlier. But that’s not all run.sh has to offer.
run::msg_ok,run::msg_err,run::msg_info,run::color_echo— helpers to print colored messages.run::icon skip,run::icon ok,run::icon err— helpers to print icons for different message types.run::promptandrun::user_input— helpers to interact with the user and get input.
And most importantly – run::friday_deploy for those who tend to forget what day it is:
It's Friday. Are you REALLY sure? (y/N) y
Ok, you're the boss...
┓┏┓┏┓┃
┛┗┛┗┛┃⟍ ○⟋ Friday
┓┏┓┏┓┃ ∕ deploy,
┛┗┛┗┛┃ノ) good
┓┏┓┏┓┃ luck!
┛┗┛┗┛┃
┓┏┓┏┓┃
┛┗┛┗┛┃
┓┏┓┏┓┃
┃┃┃┃┃┃
┻┻┻┻┻┻ You can find all available variables and helper functions along with their descriptions both in the documentation and in the run script itself.
Adding more variables and helpers
A good task runner should be extensible. And run.sh does this in the most natural way for shell scripts – by sourcing an RC file.
If you put a .runrc file in your project root, run.sh will automatically source it at launch. This is a good place to define project-specific environment variables:
BINARY="$PROJECT_ROOT/imgproxy" .runrc can also be a home for your custom helper functions. For example, it may be handy to wrap repeated run::require_tool calls:
require_tool_go() {
run::require_tool go "go is required, see https://go.dev/doc/install"
}
require_tool_docker() {
run::require_tool docker "docker is required, see https://docs.docker.com/get-docker/"
} Remember how we struggled with automatically running tasks inside Docker containers? Now that we got rid of make limitations, we can add a helper function to handle this seamlessly:
guard_docker() {
if [ -n "${IMGPROXY_IN_BASE_CONTAINER:-}" ] || [ -n "${CI:-}" ]; then
return 0
fi
require_tool_docker
run::msg_ok "switching to docker..."
local -a tty_flags=(-i)
if [ -t 0 ] && [ -t 1 ]; then
tty_flags+=(-t)
fi
local rc=0
docker compose -f "${PROJECT_ROOT}/.devcontainer/docker-compose.yml" run --rm "${tty_flags[@]}" imgproxy \
bash "./run" "$TASK_NAME" "$@" || rc=$?
exit "$rc"
} The new code is larger than the original, but that’s because it adds checks the older version didn’t.
But most importantly, all the machinery with .PHONY and hidden targets is gone. It turned into a single guard_docker call:
main() {
guard_docker
go test
} Explaining run.sh to AI agents
We designed run.sh primarily as in interface humans would use to interact with the project tasks. But, we live in the new era. Our digital colleagues, such as Claude Code or Codex should also be able to understand and use these tasks effectively.
By default, Claude and other AI CLI assistants would default to standard go or rust tasks in their plans. To make them aware of the custom run.sh tasks, you need to explain everything in your project AGENTS.MD file.
For example, that’s how we explain our project structure to Claude:
## Running tasks: use `./run`
All build, test, lint and run workflows go through the `./run` dispatcher.
Do not call `go build`, `go test`, `golangci-lint`, `gofmt` or `clang-format` directly.
- `./run` lists tasks.
- `./run help <task>` shows a task's usage.
- Tasks live in `bin/<name>.sh`. Shared config is in `.runrc`.
- Extra args pass through to the underlying tool. Example: `./run test -run TestFoo ./processing/...`.
### Tasks for everyday work
| Task | Use it for |
|---|---|
| `build` | Compile to `./imgproxy`. See the note below. |
| `run` / `build-and-run` | Start the server in Docker. Env vars come from `.imgproxyrc`. |
| `test` | Unit tests (gotestsum). Pass `go test` args, e.g. `-run X`, `-asan`. |
| `lint-go` | golangci-lint. Takes its args, e.g. `--timeout 10m0s`. |
| `lint-clang` | clang-format check for `.h`/`.c`/`.cpp`. |
| `lint` | `lint-go` + `lint-clang`. |
| `fmt` | `gofmt -s -w .` |
| `govulncheck` | Vulnerability scan. |
| `lychee` | Link check for README.md and CHANGELOG.md. |
| `clean` | Remove build artifacts. |
**`build` runs on the host and is not Docker-guarded.**
- It only checks that the code compiles.
- The resulting `./imgproxy` binary only works inside the Docker base image. Don't execute it on the host.
- To run the server, use `./run run` or `./run build-and-run`, which re-run themselves in Docker.
### Plans and verification
- A plan must name the `./run` tasks that verify each step. Don't write raw `go` commands.
- Minimum before calling a change done:
1. `./run test` (add `-run <Name>` to narrow it while iterating, then run the full suite once)
2. `./run lint`
- Run `./run fmt` after editing Go files.
- If a task can't run (no Docker, no network), say so. Don't claim it passed. The gain of using run.sh is simple:
- One task, one file: a small, readable script in the
bin/folder. No more searching for a task definition across a hugeMakefile. - No extra dependencies: nothing is required to install and use it. Except
bash. - Handy helpers: to make task implementation a breeze.
run.sh is not a build system; there is no watch mode, parallel execution, or caching. It is a simple task runner designed to streamline project workflows while keeping things human- and agent-friendly.
Let us know if you decide to adopt run.sh in your project. We’d love to hear about your experience and any improvements you make. And of course, PRs are always welcome!