Configuration

RunCommands can be configured using TOML. The following config files can be used (in order of precedence):

  • ./runcommands.toml
  • ./commands.toml
  • ./pyproject.toml

For the first two of these, the option keys (see below) should be specified like so:

[globals]
x = 1

[envs]
test = {}
prod = {}

When using pyproject.toml, the option keys (see below) need to be prefixed with tool.runcommands like so:

[tool.runcommands.globals]
x = 1

[tool.runcommands.envs]
test = {}
prod = {}

The options that can be specified are:

  • globals -> A dictionary containing global variables that are also used as default args for all commands.

  • envs -> A dictionary containing env-specific global variables and/or default args.

    When an env is specified, the corresponding env-specific variables will be merged into globals and the entire envs dict will be added to globals.

    In addition, if an env specifies args, these will be used as default args when the env is selected. These default args have higher precedence than default args specified via the top level args option (see below).

    The selected env’s args will not be added to globals.

  • args -> A dictionary containing default arg values for specific commands. Note that if an env is specified, the env’s default args, if any, will take precedence over args (see above).

  • environ -> Environment variables.

globals and environ correspond to the globals and environ options of the runcommands.run.run() command.

Order of Precedence

Lowest to highest:

  1. Keyword args
  2. Global args from config file
  3. Global args passed via run command
  4. Env-specific global args from config file
  5. Env-specific default args from config file
  6. Default args from config file
  7. Default args read from environment variables
  8. Command line args
  9. Direct call args

Interpolation

String values may contain interpolation groups using dotted notation to refer to other configuration values like so:

[globals]
x = "{{ y }}"
y = 1
z = "z {{ y }} z"

When a value contains a single interpolation group and nothing else, it will be replaced with the exact value that it refers to, so in the example above, x will be equal to the integer 1 and z will be equal to the string "z 1 z".

Globals are injected into other global args, default args, and environment variables (after env-specific args are merged in).

Default args are injected into other default args.