Tasks

Tasks are defined in a minimal.toml file, and describe a runtime environment + command invocations to be executed using mip 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 stack.

[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"]

When exec names a command without an absolute path (or a ./ prefix), the command is resolved to /bin/<command> inside the sandbox — in the examples above, pnpm runs as /bin/pnpm.

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}!\""

description - Describe the task

Optional

description is a free-text description of the task, shown alongside the task name in mip status.

[tasks.my_task]
description = "Run the dev server with hot reload"

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 tilde is expanded to the user's 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}"

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

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

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

Each argument's datatype may be:

• a scalar: "string", "number", or "boolean" (alias "bool");
• an array of a scalar type: "Array string", "Array number", "Array boolean";
• an enum of permitted values, written either as the string "[a, b]" or as a TOML array ["a", "b"].

Instead of a bare datatype string, an argument can be declared as a table with a type field plus optional help (a human-readable description) and default (making the argument optional):

[tasks.greeter]
args.name = { type = "string", help = "who to greet", default = "world" }
exec = "echo Hello %{name}"