Variables

Variables are used inside task definitions using the dollar sign $. Tasks you run will not be aware of variables used like this because CJTaskrunner swaps them out for their values before sending arguments to the task.

Variables in CJTaskrunner are runtime values, exported, or environment variables.

Environment variables can be used the same way as runtime variables, and are also visible to child processes. For example, $PATH is an environment variable that programs read from the shell environment.

@set NAME value sets a CJTaskrunner runtime variable.

Runtime values are passed into subordinate @task and @await calls as a snapshot, but runtime variables set inside of a task do not persist to the calling task.

@set NAME: runs its indented block with stdout capture enabled, trims trailing line endings, and stores the captured text. Capture fails when the block’s final status is non-zero.

branch:
  @set BRANCH:
    git rev-parse --abbrev-ref HEAD
  @echo $BRANCH

@export also exposes the value to child processes, making it an environment variable for processes within the taskfile execution context.

@unset removes a runtime value and export.

Runtime variables are reset after the task exits.

Variables are not allowed in @desc or @help: text.

Environment

Set multiple variables at once using an @env: block:

@env:
  NAME: value
  FALLBACK?: fallback value

NAME: value overrides an inherited value. NAME?: value only applies when the variable is absent.

Additionally, you can use @export to set environment variables or turn a runtime variable into an environment variable.

CJTaskrunner runs in an isolated snapshot of your environment, which we refer to as the taskfile execution context.

• Existing environment variables can be used within taskfiles.
• If you set a variable using an existing variable name in your taskfile, that new value will take precedence for the duration of the task context.
• The overridden environment variable will be restored after the task context ends unless exported.
• Variables that are exported will propagate to other tasks within the same taskfile execution context, for example when tasks call other tasks. These propagate back to a calling task as well.
• Exported variables work essentially the same way as environment variables. In case of a conflict, exported variables take precedence.

Interpolation

Variables can be used in directives or task commands. There is only simple interpolation available.

Variables are resolved before sending to commands.

Directive operands are treated as strings after interpolation; when a directive expects a variable name, the interpolated string is validated as the name.

show:
  @echo $NAME
  @echo "${NAME}"
  @echo ${OPTIONAL?}
  @echo ${PORT?5173}
  @echo ${MESSAGE?"hello world"}

Rules:

• $NAME expands to the current value and errors when absent.
• ${NAME} expands to the current value and errors when absent.
• ${NAME?} expands to the current value or an empty string when absent.
• ${NAME?fallback} uses fallback when the variable is missing.
• ${NAME?"fallback value"} supports a quoted fallback.
• In ordinary commands, an interpolated value remains one argv value.
• In @shell, interpolated values are shell-quoted before /bin/sh -c.

Version Variables

@version cli 0.1.0

Version declarations create variables named VERSION_<NAME>, with the name uppercased and hyphens converted to underscores. The example above creates $VERSION_CLI. See SemVer Tools for more info.