url and run
url downloads the given URL to a disk cache and prints its path.run takes a URL or domain name, appends a well-known path and executes what it finds there, with zsh integration so you can run URLs or bare domains directly.
The specifications separate the url command, the run command,
and their shared URL resolution contract.
To learn how to publish software for run read this user guide.
It's also an agent skill, which you can install into a project with:
mkdir -p .agents/skills
cp -R "$(url hydraulic-software.github.io/url/skills/run-tutorial.zip/run-tutorial/)" .agents/skills/
Intro
$ run --install
$ url https://raw.githubusercontent.com/hydraulic-software/url/refs/heads/master/README.md
/Users/mikehearn/Library/Caches/./entries/8d/0f/8d0fd7ca687ebe77/content/README.md
$ https://example.com --version
They're like curl, but simpler when you don't want to manage the downloaded files. Useful with substitutions!
The cache uses a versioned v2 subdirectory inside the selected cache directory.
Entries from the previous layout are ignored and downloaded again; the old
entries can be deleted.
url cleans up the cache when it grows too large, and refuses new downloads
when less than 100 MB is free, and checks space throughout downloads and
extraction. Override the threshold with
--min-free-space=MB or URL_MIN_FREE_SPACE_MB; use 0 to disable the guard.
Downloads and archive extraction check the destination's available space as
work proceeds, including cache copies during revalidation. There is no fixed
limit on response size, expanded archive size, or archive entry count. Disk-space
refusals clean up their partial files immediately. Other failed builds retain
their working files for investigation. Existing cache hits remain usable
without downloading or extracting again.
On POSIX systems, cache directories are made private (mode 0700), and
extracted files cannot be group- or world-writable. A POSIX cache directory
must be a real directory rather than a symbolic link.
The https:// part is optional:
$ file `url hydraulic.dev`
/Users/mikehearn/Library/Caches/dev.hydraulic/url-tool/entries/14/35/14353bf86b68943b/content/download: HTML document text, Unicode text, UTF-8 text, with very long lines (26118)
Pass -r or --refresh to ignore a cached HTTP response and download it again.
By default, command failures print a concise diagnostic. Pass --verbose, or
set URL_VERBOSE=1, to include the full exception and cause stack trace.
Building
Run ./build.sh nativePair to build the native executables. If url is already
on PATH, the script resolves Oracle GraalVM 25 through the URL cache and points
Gradle at that JDK; otherwise it delegates directly to ./gradlew.
./gradlew installDist creates both bin/url and bin/run launchers in the
installed distribution. The default development version is development; set
-PurlVersion=VERSION for a release build.
Archives
When a URL contains a .zip or tarball, paths within the archive can be appended and url will print the path to
that file within the extracted archive. / at the end counts as the root of the archive:
$ url https://github.com/sharkdp/bat/archive/refs/tags/v0.26.1.zip
/Users/mikehearn/Library/Caches/./entries/45/99/4599d2be0fea81b5/content/v0.26.1.zip
$ url https://github.com/sharkdp/bat/archive/refs/tags/v0.26.1.zip/
/Users/mikehearn/Library/Caches/entries/33/e8/33e8825e5015aac5/content
$ ls `url https://github.com/sharkdp/bat/archive/refs/tags/v0.26.1.zip/`
assets Cargo.lock CHANGELOG.md diagnostics examples LICENSE-MIT README.md SECURITY.md tests
build Cargo.toml CONTRIBUTING.md doc LICENSE-APACHE NOTICE rustfmt.toml src
$ head -n 1 `url https://github.com/sharkdp/bat/archive/refs/tags/v0.26.1.zip/NOTICE`
Copyright (c) 2018-2021 bat-developers (https://github.com/sharkdp/bat).
Archives may be nested, for example url example.com/outer.zip/dir/inner.zip/file.txt.
Remote tar archives are decompressed directly from the HTTP response into the
extraction cache, so the compressed tarball is not retained. If that exact
tarball is already in the download cache, the local copy is reused. Supported
tar forms are uncompressed .tar, gzip (.tar.gz and .tgz), bzip2 (.tar.bz2), XZ
(.tar.xz), Zstandard (.tar.zst and .tar.zstd), and UNIX compress
(.tar.Z); ZIP is also supported but requires a seekable cached file, including
entries compressed with Zstandard method 93.
Extraction stays in-process, consistently across Linux, macOS, and Windows,
without depending on locally installed tools.
Timestamped run packages reject file path components containing literal
backslashes or newlines. Paths in the authenticated manifest are constructed
from filesystem components joined with /, so Unix filenames cannot alias
nested paths. The Unix package builder rejects these filenames as well.
Proxies
HTTP requests honor the conventional http_proxy, https_proxy, and
no_proxy environment variables (with uppercase aliases also accepted).
no_proxy accepts comma-separated hosts or domain suffixes, optional ports,
and * to bypass proxies for every request.
Progress tracking
If stderr points to an interactive terminal then url emits OSC progress bar events. Modern terminal emulators like
iTerm2 can render these nicely in the UI. Use -p or --progress=bar for an animated Unicode progress bar. run
uses that bar by default when stderr is connected to an interactive terminal. Because stderr is inherited this works
even inside substitutions.
Progress events can be emitted as JSON or plain text if you wish also.
Resolving into shell variables
Prefix every URL with a portable shell variable name to resolve them in
parallel and emit safely quoted assignments:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
