version: "1.0.1" name: dload-fetch-tool description: Get a CLI tool — native binary or PHAR — from a GitHub or GitLab release (public or self-hosted) into a project folder with dload (vendor/bin/dload). Use when the user wants tool X (rr, temporal, buf, a PHAR…) downloaded into the project or added to dload.xml, when a download picks the wrong asset or none, or when setting up dload's release cache (version registry) locally or in CI, including GitHub API rate limits.

Download a GitHub binary or PHAR into a project with dload

The task — "tool X from GitHub, available in this project's folder" — turns on one question: does dload already know this tool? If yes, dload.xml gets one <download> line. If no, the tool is also described inline in the same file. Native binaries and .phar files are both first-class; they differ in a couple of fields.

Everything happens in the consuming project's own dload.xml (dload itself is installed via composer require internal/dload).

Step 1 — check what dload already knows

./vendor/bin/dload software

Prints every tool dload knows with its alias and, in brackets, its source: official, dload.xml, or the Composer package that declares it. Tool listed → Step 3. Not listed → Step 2.

Step 2 — describe a missing tool inline

Add a <software> block to the <registry overwrite="false"> element of the project's dload.xml. Read `references/registry-entry.md` first: it lists the facts to collect from the GitHub release and how to design asset-pattern and binary.pattern for binaries and PHARs.

Done when the block has a <repository> whose asset-pattern matches every OS/arch variant of the tool and nothing else in the release.

When the tool is needed by a Composer package (a framework, a CMS) rather than by one project, the package declares the block for every project that installs it: read `references/package-registry.md`.

Step 3 — add the <download> action

<?xml version="1.0"?>
<dload
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/php-internal/dload/refs/heads/main/dload.xsd"
    temp-dir="./runtime"
>
    <actions>
        <download software="buf" />
        <download software="trap" type="phar" version="^1.1" />
    </actions>
    <registry overwrite="false">
        <!-- inline <software> blocks from Step 2, if any -->
    </registry>
</dload>

type="archive" is for tools that ship more than one executable — frontend bundles, docs, a binary that loads sibling libraries by relative path. Read `references/archive-mode.md` before using it.

The authoritative schema is vendor/internal/dload/dload.xsd.

Step 4 — pick the destination folder

<actions>
    <download software="rr" extract-path="./bin" />
    <download software="trap" type="phar" extract-path="./tools" />
</actions>

extract-path is the literal folder the file lands in, for binaries and PHARs alike. Keep the folder in VCS with a .gitkeep and put the downloaded file in .gitignore — only dload.xml belongs in git.

Step 5 — run dload and verify

./vendor/bin/dload get             # every <download> entry in dload.xml
./vendor/bin/dload get <alias>     # one entry

Done when the tool runs: ./bin/rr --version, php ./tools/trap.phar --version.

Release lists are answered from a local cache — the version registry — for 10 minutes after the last check of a repository, so a release published moments ago may need dload get --refresh. For cache location and TTL, and for any CI setup — passing GITHUB_TOKEN and carrying the registry between runs, with GitHub Actions and GitLab examples — read `references/version-registry.md`.

When the download fails

dload get exits non-zero and prints, per failed tool, the API error, the releases it checked, their assets, and the filter that rejected them. Read that report, then walk the selection stages in `references/troubleshooting.md`.