Run shell commands

The experimental_shell_command target allows you to run any command during a Pants execution, for the purpose of its side-effects when accessing services over the network, or modifying or creating files to be used by other targets, or simply to manage some external service etc. The command is limited to operating on the specific set of input files provided as dependencies, and only produces output files for other targets to consume. It is not possible to mutate any file in the workspace.

📘

Idempotency requirement

The shell command may be cancelled or retried any number of times, so it is important that any side effects are idempotent. That is, it should not matter if it is run several times, or only partially.

experimental_shell_command(
    command="./my-script.sh download some-archive.tar.gz",
    tools=["curl", "env", "bash", "mkdir", "tar"],
    outputs=["files/"],
    dependencies=[":shell-scripts", ":images"]
)

shell_library(name="shell-scripts")
files(name="images", sources=["*.png"])

#!/usr/bin/env bash
case "$1" in
    download)
        echo "Downloading $2..."
        curl https://my-storage.example.net/blob/$2 -O
        mkdir files && tar xzf $2 -C files ;;
     *)
        echo "Usage: $0 [download|...]" ;;
esac

The experimental_shell_command

The command field is passed to bash -c <command>, with any files from listed dependencies in the working directory tree. Any executable tools that might be used must be specified in the tools field, in order to be available on the PATH while executing the command.
In case there are resulting files that should be captured and passed to any consuming targets, list them in the outputs field. To capture directories, simply add the path to the directory, with a trailing slash (as in the example ”files/”, above).

🚧

Feedback wanted

We are gathering feedback on this target before we promote it from its experimental status. Please reach out to us on slack or GitHub with your ideas or issues.

The experimental_run_shell_command

TBW...