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:

$ resolved=$(url "jdk=$jdk_url" "jar=$jar_url") && eval "$resolved"
$ "$jdk/bin/java" -jar "$jar" --help

Named inputs cannot be mixed with ordinary URL inputs or custom output separators. An = inside a URL path or query string remains part of the URL.

Running programs

run foobar.com --help resolves https://foobar.com/run.zip/run.js, evaluates its launch plan, and passes --help to the resulting executable. The JavaScript script describes which URLs to resolve and the final executable to launch, so the package can select the right binary for each platform without a shell wrapper.

Because of the caching, this means the program at foobar.com will keep itself up to date automatically.

During development, pass a local launcher directory or run.zip file to bypass URL resolution and the cache. A directory must contain run.js; a zip file must contain run.js at its root. run forwards all remaining arguments:

$ run ./run.zip.d --help
$ run ./run.zip --help

Paths beginning with ./, ../, or / are always treated as local paths; missing paths fail instead of being interpreted as URLs. A local run.zip is extracted to a temporary directory for the duration of the command.

The black-box compliance checks can be run against a native executable with RUN_BIN=./build/native/nativeCompile/run python3 scripts/run-compliance.py.

The package accesses context.os, context.arch, nullable context.ver, context.args, context.packageDir, the absolute working directory context.cwd, and the platform cache root context.cacheDir. The cache root follows the platform convention (~/Library/Caches on macOS, $LOCALAPPDATA or ~/AppData/Local on Windows, and $XDG_CACHE_HOME or ~/.cache elsewhere). The host does not create or grant access to this directory. A package can use a reverse-DNS application subdirectory and request std.files.write for that path; the write grant includes reads. This is separate from run's own --cache-dir. The host functions are asynchronous and return promises, so a package uses top-level await. url() resolves one URL to a path. urls() takes an array of URLs or a map whose values are URLs or arrays of URLs, resolves all entries concurrently and returns paths in the corresponding array or map shape:

const {java, jar} = await urls({
  java: `https://example.com/jdk-${context.os}-${context.arch}.tar.gz/bin/java`,
  jar: "https://example.com/app.jar",
});
export default {executable: java, arguments: ["-jar", jar, ...context.args]};

Inspect a package before launching it with run --dry example.com/tool args or run -d ./run.zip.d args. This evaluates and caches its resources, prints the executable, arguments and effective permissions to stdout, and exits without launching. Put -d before the target; after it, the flag goes to the package. With the installed zsh integration, prefix a command with ?: ?example.com/tool args, ?https://example.com/tool args, or ?./run.zip.d args.

Packages can compute permissions from their arguments and working directory:

export default {
  executable: await url("https://example.com/compiler"),
  arguments: context.args,
  permissions: {
    "std.files.read": [context.cwd],
    "std.files.write": ["out"],
    "std.environment": ["CC_*"],
    "std.network.client": false,
  },
};

Omitting permissions runs unrestricted. An empty object requests only the baseline: package and resolved cache entries, system libraries and programs, stdio and terminal, a private temporary directory, and PATH, HOME, TERM, LANG, and LC_*. Write grants include read access. Relative paths use context.cwd; symlinks in existing prefixes resolve to their targets. Unknown permission keys are ignored and listed in dry runs.

On macOS, executables outside .app bundles run through Seatbelt when sandbox-exec is available: file and network access are restricted, restrictions apply to children, and Launch Services is denied. App bundles currently receive only environment filtering and a private temporary directory, pending App Sandbox support. Linux and Windows likewise apply environment filtering and private temporary directories; file and network enforcement is deferred. Normal launches do not warn about permissions the platform cannot enforce; dry runs show enforcement status. Semantics use the verified package timestamp date, or the current UTC date, with std.semantics allowing an opt-in to later rules. See specs/run.md for the permission contract.

Every call starts immediately and runs concurrently with the others, so modules imported side by side resolve their URLs in parallel without coordinating. A rejected promise that the package does not handle fails the run. The default export is the launch plan. On Windows, executable URLs and launch-plan executable paths may omit their final .exe suffix.

compose() assembles a new cached directory from paths returned by url(), urls() or earlier compose() calls. It takes an ordered array of copy operations ({from, select, to, replace}) and removal operations ({remove}), and returns a promise for the assembled directory's path. A from value may be a promise, so composition starts as soon as its sources are ready:

const base = url("https://example.com/app.zip/");
const patch = url("https://example.com/patch.zip/");
const app = await compose([
  {from: base, to: "."},
  {remove: "plugins/legacy"},
  {from: patch, select: "bin/tool", to: "bin/tool"},
]);

The result is cached by its recipe and the identity of its sources, so it is rebuilt only when the recipe changes or an unlocked source is downloaded again. See specs/run.md for the exact copy, path and symbolic link rules.

Packages may import other JavaScript files from their own directory using relative ECMAScript module imports.

run.zip can contain anything but it's conventional and strongly recommended that:

• It keep run.js small. The package should describe the launch rather than contain the downloaded program.
• It use url values with archive members when a program lives inside an archive.
• It run downloaded programs from inside the disk cache, not copy them elsewhere or install them.

Security

url sets the +x bit on UNIX automatically for files that are detected to be native binaries or have a hashbang line.

URLs can be hash locked by adding #sha256=..... A mismatch will cause url to exit with an error code and no path is printed. For archive members and extracted directories such as tool.zip/ the hash is of the (innermost) archive itself. A nested archive URL such as outer.zip/inner.zip returns the inner archive file; append / to extract its root directory.

On macOS, url quarantines downloads and extracted archive entries so Gatekeeper can assess them when opened. Pass --no-gatekeeper to omit quarantine metadata; this also removes it from cached results, and archives are extracted separately under each setting. run quarantines resources by default. For a target inside a .app bundle, it quarantines the whole bundle and lets macOS handle the first launch. For a standalone Mach-O executable, it checks the signature and notarization with codesign --verify --strict -R=notarized --check-notarization and removes quarantine only after that check succeeds. Validly signed but unnotarized binaries are refused pending a future third-party notarization option. Unsigned binaries prompt on an interactive console and are refused otherwise; an explicit override removes quarantine before launch. run --no-gatekeeper skips these checks and quarantine handling. These checks only approximate Gatekeeper: macOS also applies its own malware detection, certificate revocation, and launch policies. Quarantine changes run as the current user and do not request sudo; they can fail if file ownership or filesystem protections prevent changing the attribute.

File lists

You can pass lists of URLs via stdin:

$ url <<'EOF'
# This is a comment
https://github.com/sharkdp/bat/archive/refs/tags/v0.26.1.zip#sha256=7e4ce5325c1fee3fc80a26324e203e7c5ed89096cf7c4bdc67d61a97f612c912

# Another comment
https://github.com/sharkdp/bat/releases/download/v0.26.1/bat-v0.26.1-x86_64-apple-darwin.tar.gz#sha256=830d63b0bba1fa040542ec569e3cf77f60d3356b9de75116a344b061e0894245
EOF
/Users/mikehearn/Library/Caches/./entries/45/99/4599d2be0fea81b5/content/v0.26.1.zip
/Users/mikehearn/Library/Caches/./entries/73/8f/738fa741db39ddc1/content/bat-v0.26.1-x86_64-apple-darwin.tar.gz

Blank lines and lines whose first non-whitespace character is # are ignored. Inputs resolve concurrently with bounded parallelism, while their paths are printed in input order. Each resulting path is newline-terminated by default; use --print0 for NUL termination or --print-separator=: to construct output such as a classpath.