Note
As of 2024-12-28, wrun is deprecated and this project is archived, no future work or releases are planned. The problem wrun set out to solve has multiple solutions already that work great, for example (but not limited to) mise and aqua.
wrun
downloads, caches, and runs an executable,
with the same one command for multiple OS/architectures.
The primary use case for what it was created is to be able to use a single static command line to download and invoke executables in git pre-commit hooks, without OS or architecture conditionals.
Executables to download can be standalone as-is, or inside archives. Downloads are cached locally, and optionally checksum verified on download.
Detailed usage message
$ wrun --help
wrun downloads, caches, and runs executables.
OS and architecture matcher arguments for URLs to download and (if applicable) executables within archives can be used to construct command lines that work across multiple operating systems and architectures.
The OS and architecture wrun was built for are matched against the given matchers.
OS and architecture parts of the matcher may be globs.
Order of the matcher arguments is significant: the first match of each is chosen.
As a special case, a matcher argument with no matcher part is treated as if it was given with the matcher */*.
On Windows, .exe is automatically appended to any archive exe path resulting from a */ prefixed match.
URL fragments, if present, are treated as hashAlgo-hexDigest strings, and downloads are checked against them.
The first non-flag argument or -- terminates wrun arguments.
Remaining ones are passed to the downloaded executable.
Environment variables:
- WRUN_ARGS_FILE: path to file containing command line arguments to prepend, one per line
- WRUN_CACHE_HOME: cache location, defaults to wrun subdir in the user's cache dir
- WRUN_OS_ARCH: override OS/arch for matching
- WRUN_VERBOSE: output verbosity, false decreases, true increases
Usage:
wrun [flags] -- [executable arguments]
wrun [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
generate generate wrun command line arguments for various tools
help Help about any command
Flags:
-p, --archive-exe-path strings [OS/arch=]path to executable within archive matcher (separator always /, implies archive processing)
-n, --dry-run dry run, skip execution (but do download/set up cache)
-h, --help help for wrun
-t, --http-timeout duration HTTP client timeout (default 5m0s)
-u, --url strings [OS/arch=]URL matcher (at least one required)
-v, --version version for wrun
Use "wrun [command] --help" for more information about a command.
Prebuilt binaries are available in project releases, apt and yum package repositories at Packagecloud.
Prebuilt binaries are also available from PyPI,
in the wrun-py
package,
installable for example with pip
:
python3 -m pip install wrun-py
To build and install from sources, Go is required.
go install github.com/scop/wrun@latest
URLs are matched against the Go toolchain wrun was built with using
the OS/architecture=
prefix given along with the URLs. Valid values
for these come from Go, the list is available by running
go tool dist list
, or from
Go sources.
OS and architecture may contain globs. The special case where the
OS/architecture=
prefix is left out is treated as if */*=
was
given.
Order of specifying the URLs is significant; the first matching one is chosen.
To verify downloads against known good digests, place a digest in the URL
fragment.
The fragment format to use is digestAlgo-hexDigest
.
For example:
#sha256-2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9842
Usage with lefthook
See .lefthook.yaml
in this repo for an example.
Note that because in this repository we want to dogfood the latest wrun itself,
we invoke go run .
instead of wrun
.
Another example is in
scop/vault-token-helper-secret-tool.
See its .lefthook.yaml
for how it runs wrun in the lefthook managed git pre-commit hook, and its
.github/workflows/check.yml
for how it installs wrun and installs and runs lefthook in CI.
Usage with pre-commit
See .pre-commit-config.yaml
examples in
.pre-commit-hooks.yaml
.
pre-commit.ci is not supported, because it disallows network access at runtime.
Cache resides by default in the wrun
subdirectory of
the user's cache directory.
$WRUN_CACHE_HOME
overrides it.
Cache the cache dir in CI to avoid unnecessary executable downloads. A GitHub actions example is in this repository's workflow configs.
The generate
subcommand can be used to generate wrun command line arguments for various tools.
It supports tools shipped in GitHub releases and PyPI executable wrapper wheels that meet its expectations about asset filenames regarding their OS and architecture.
Some additional tool specific generators are available as well for tools that are not served by the generic GitHub and PyPI generators.
See wrun generate --help
for more information.
generate output excerpts
$ wrun generate --help
[...]
Available Commands:
black generate wrun command line arguments for black
github generate wrun command line arguments for tool in GitHub project asset
pypi generate wrun command line arguments for tool in PyPI project wrapper wheel
shellcheck generate wrun command line arguments for shellcheck
terraform generate wrun command line arguments for terraform
[...]
$ wrun generate github --help
[...]
Examples:
wrun generate github aquasecurity trivy
wrun generate github astral-sh ruff
wrun generate github astral-sh uv --tool uvx
wrun generate github daveshanley vacuum
wrun generate github dprint
wrun generate github golangci golangci-lint
wrun generate github hadolint
wrun generate github mvdan sh --tool shfmt
wrun generate github opentofu --tool tofu
[...]
$ wrun generate pypi --help
[...]
Examples:
wrun generate pypi committed
wrun generate pypi ruff
wrun generate pypi typos
[...]
By default, generate
generates command line arguments pointing to the version of the executable in question that it considers the latest.
This mode together with wrun's ability to load command line arguments from a file
can be used to help with automating executable updates.
An example of this is in this repo's .lefthook.yaml
(lefthook part, see the update-tools
"hook" in it),
and .github/workflows/update-tools.yaml
(CI part).
#98 is an example automated pull request automatically created by this config.
(See the note about go run .
vs wrun
in the lefthook chapter above.)
The PR creation part of that makes use of the peter-evans/create-pull-request
GitHub action, but naturally the generate
subcommand could be run manully and its output copy pasted to appropriate configuration file,
and the related PR created manually.
Renovate e.g. along with its regex manager could be used to achieve the same. However, at time of writing (2024-12), download digests are not doable with it, and thus this approach, while possibly more convenient, is arguably inferior compared to the above.
SPDX-License-Identifier: Apache-2.0