Reference¶

• Install
• Scripts
• Usage
• Environment

The CLI executable is run or toml-run and help is available with --help.

usage: run [-l] [-c CONFIG] [-s] [-v] [-V] [-D] [-h] [name]  # (1)!

example: run [name] -- --script-args

positional arguments:
  name                 Name of script to run

options:
  -l, --list           List available scripts
  -c, --config CONFIG  Config [default: pyproject.toml]
  -s, --silent         Disable script output
  -v, --verbose        Verbose output [debug: -vvv]
  -V, --version        Show installed version
  -D, --docs           Launch docs in browser
  -h, --help           Show this help message

1. Tip: Save your options with Environment Variables.

To view the source code, see the cli.py on GitHub.

Install¶

From PyPI: https://pypi.org/p/toml-run
GitHub: https://github.com/cssnr/toml-run

uv tool install toml-run

uv add --dev toml-run

pip install toml-run

pip install --group dev toml-run

brew install cssnr/tap/toml-run

Upgrade.

uv tool upgrade toml-run

uv sync --upgrade-package toml-run

pip install -U toml-run

pip install -U toml-run

brew update && brew install toml-run

Uninstall.

uv tool uninstall toml-run

uv remove --group dev toml-run

pip uninstall toml-run

pip uninstall toml-run

brew uninstall toml-run

Run without installing using astral-sh/uv .

uvx toml-run

Check the installed --version.

run -V

Scripts¶

Scripts are defined in the pyproject.toml using the [tool.scripts] section.

[tool.scripts]  # (1)!
build = "uv run hatch build"

1. Supported headings: [tool.scripts] and [tool.toml-run]

Define "pre" and "post" scripts by prefixing the script name.

prebuild = "echo always run before build"
build = "echo running build"
postbuild = "echo always run after build"

Split commands into multiple commands.

as-list = ["echo one", "echo two"]
as_string = """
echo one
echo two
"""

Chain commands and run other commands.

one = "echo one"
two = "run one && echo two"
success = "run one && echo success || echo failed"
failure = "run abc && echo success || echo failed"

All paths are relative to the config file directory.

clean = "rm -rf dist"

Therefore, clean will always remove this dist folder.

.
├── pyproject.toml
└── dist

Run Python code using eval easily.

unlink = "#py Path('file').unlink(True)"
rmtree = "#py shutil.rmtree('dir', True)"
web = "#py webbrowser.open_new_tab('https://github.com/cssnr/toml-run')"
chain = ["run rmtree", "#py print('two')", "echo three", "run web"]

You can use these in a list and with run just not using &&. The only parsing done is looking for #py at the start of a string and running eval. You can view the list of imported modules below.

import os
import shutil
import subprocess
import sys
import webbrowser
from pathlib import Path
from pprint import pformat

Usage¶

The CLI executable is run or toml-run.

List available scripts with --list.

run -l

Run a script with run.

run build

Run without installing using astral-sh/uv .

uvx toml-run build

Pass additional arguments after -- terminator.

run build -- --clean

Increase output with --verbose. Debug with -vv or -vvv.

run build -v

Silent script output with --silent.

run build -s

If your scripts are defined in another file use --config.

run -c settings.toml build

This will look for a settings.toml in current and parent directories and run the scripts relative to that files directory.

You can set the SCRIPT_CONFIG Environment variable to avoid using the --config option every time.

Environment¶

Many options support setting environment variable defaults.

Allowed boolean values, case-insensitive.

0, f, n, no, off, false
1, t, y, on, yes, true

You can temporarily set variables on the command line.

export SCRIPT_VERBOSE=1

$env:SCRIPT_VERBOSE=1