Tasks

Tasks are defined in a minimal.toml file, and describe a runtime environment + command invocations to be executed using minimal run <taskname>

Tasks schema

Tasks are defined in a [tasks.<task-name>] block in your minimal file.

packages - Packages to be installed in the runtime environment

Optional

packages lists additional packages which will be installed in the tasks' runtime environment. Packages listed here are in addition to any installed due to the profile or harness.

[tasks.my_task]
packages = ["python"] # Additionally install python

exec or bash - What the task should do

exec describes a command or invocation that should run when the task is launched. exec can be defined either as an argv string:

[tasks.my_task]
exec = "pnpm build"

or as a program and its list of arguments:

[tasks.my_task]
exec = ["pnpm", "build"]

bash describes a bash command that should run when the task is launched.

[tasks.my_task]
bash = "echo \"hello\" > hello.txt"

When args are set on the task, arguments can be substituted into the invocation using Nickel's string interpolation syntax:

[tasks.greet]
args.name = "string"
bash = "echo \"Hello %{name}!\""

state_key - Persist state between invocations

Optional

state_key controls caching of build artifacts and files between runs.

[tasks.my_task]
state_key = "dev" # Cache build artifacts under 'dev'

env_vars - Environment variables to set

Optional, Alias vars

env_vars sets environment variables in the tasks' runtime environment. Variables set here take precedence over any inherited from the profile.

[tasks.my_task]
env_vars = {
  CC = "gcc",
  AWS_PROJECT = "zest",
}

Environment variables can also inherit their value from the parent process. To do this, declare the variable with the value { inherit = true }:

[tasks.my_task]
env_vars.TOKEN = { inherit = true }

interactive - TUI apps and shells

Optional, Default false

interactive indicates that this task must be run interactively (that is, with standard input and a tty connected).

[tasks.my_task]
interactive = true

profile - Inherit customization from a profile

Optional

profile applies the configuration in the named profile to the tasks' runtime environment.

[tasks.my_task]
profile = "dev" # Initializes package/env_vars based on the 'dev' profile

profile can be set to the empty string to avoid applying any default profile.

[defaults]
profile = "dev"

[tasks.my_task]
profile = "" # No profile applied to `my_task`

patches - Map in files/directories from the system

Optional, Alias patch

patches configures files and directories to be mapped into the tasks' runtime environment.

[tasks.my_task]
patches.dir."~/.claude" = "read-write"
patches.file."~/.claude.json" = "read-write"

patches is a structure with two optional fields, dir & file, each of which contains a mapping of file paths to be mapped in, and the corresponding map mode. The map mode may only be the string "read-only" / "ro" for read-only mappings, or the string "read-write" / "rw" for writeable mappings.

If a mapped file or directory does not exist on the host, an empty file or directory is created.

Mapped paths must be absolute or start with ~, in which case the tilda is expanded to the users' home directory.

inherit_cwd - Use parent working directory instead of repository root

Optional, Default false

inherit_cwd configures minimal to setup the task in the current working directory, instead of the repository root.

[tasks.my_task]
inherit_cwd = true

args - Pass arguments to tasks

Optional

args configures named arguments and their datatype, which can be substituted into the command being executed by the task.

[tasks.greeter]
args = {
    name = "string",
    greeting = "string",
}
exec = "echo %{greeting} %{name}"

All arguments become mandatory for invoking the task. In the example above, running the task greeter without its two arguments will trigger an error:

$> minimal run greeter
error: the following required arguments were not provided:
  --name <name>
  --greeting <greeting>

Usage: minimal run greeter --name <name> --greeting <greeting>

Valid datatypes are string, number, and boolean.