PURL-TOOL(1p)

📦
version 2.25 · 2 versions
, in ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

okay bestie, meet purl-tool — literally just the Package URL tool. that's the whole name, she's simple 💅 this is the user-contributed Perl documentation for her, so you're in exactly the right place 🫶

✨ SYNOPSIS ✨

so here's how you actually call her:

purl-tool [OPTIONS]...STRING
purl-tool --type STRING [--namespace STRING] --name STRING [--version STRING] [--subpath STRING] [--qualifier KEY=VALUE [...]]

^ that's "hand me a string and I'll deal with it" mode, and "build me one from scratch" mode. then there's the classic:

purl-tool [--help|--man|-v]

because sometimes you just need help, the whole manual, or the version number. no cap.

🎀 Options

  • --info TYPE — shows you the deets on the PURL type you name. like, information about provided PURL type. obsessed
  • --list — dumps out the known PURL type(s) it has.
  • --help — the brief help message. quick, cute, to the point.
  • --man — the full documentation. the whole novel.
  • -v — prints the version, that's it, that's the tweet.
  • -q, --quiet — shhh 🤫 suppress output.

🌈 "purl" string encode options

these are the ones that build a PURL for you:

  • --type=STRING — the Type.
  • --namespace=STRING — the Namespace (optional, bestie, it says so right there).
  • --name=STRING — the Name.
  • --version=STRING — the Version (optional).
  • --qualifier KEY=VALUE — a Qualifier key-value (optional).

🦋 "purl" string decode options

these take a PURL and hand stuff back to you:

  • --download-url — gives you the Download URL.
  • --repository-url — gives you the Repository URL.
  • -0, --null — returns a NULL char instead of a new line. iconic for scripting, fr fr.
  • --format=FORMAT — sets the Output format.
  • --dumper — Data::Dumper format (same thing as --format=dumper).
  • --json — JSON output format (same thing as --format=json).
  • --yaml — YAML output format (same thing as --format=yaml).
  • --env — ENV output format (same thing as --format=env).

🫶 "purl" validation options

  • --validate — validates a PURL string and returns the exit code. so you can straight up if on it. main character behaviour, honestly.

⭐ Examples from the synopsis

parse the given Package URL string and return JSON, then send the STDOUT to jq:

purl-tool pkg:cpan/GDT/URI-PackageURL@2.24 --json | jq

download the package from the repository using the PURL string:

wget $(purl-tool pkg:cpan/GDT/URI-PackageURL@2.24 --download-url)

create a canonical PURL string:

purl-tool --type cpan \
          --namespace GDT \
          --name URI-PackageURL \
          --version 2.24

validate a PURL string:

if $(purl-tool $PURL_STRING --validate -q); then
    echo "PURL string is valid"
else
    echo "PURL string is not valid"
fi

display information about the provided PURL type (allowed components, repository, examples, etc.):

purl-tool --info rpm

display all known PURL types:

purl-tool --list

💖 DESCRIPTION 💖

purl-tool — Package URL tool. that's it. that's the description.

so. a Package URL (aka a "purl", the nickname is right there) is a URL string used to identify and locate a software package in a mostly universal and uniform way — across programing languages, package managers, packaging conventions, tools, APIs and databases. it's the ✨lingua franca✨ of package identity, and honestly? it ate.

the spec lives here, go read it, it's a whole slay: <https://github.com/package-url/purl-spec>

a purl is a URL composed of seven components:

scheme:type/namespace/name@version?qualifiers#subpath

and the components are separated by a specific character, so the parsing is unambiguous — no guessing games, periodt.

here's the definition for each component:

  • scheme — the URL scheme, with the constant value of pkg. one of the primary reasons for this single scheme is to facilitate the future official registration of the pkg scheme for package URLs. Required.
  • type — the package type or package protocol, like cpan, maven, npm, nuget, gem, pypi, etc. Required.
  • namespace — some name prefix, like a Maven groupid, a Docker image owner, a GitHub user or organization. Optional and type-specific.
  • name — the name of the package. Required.
  • version — the version of the package. Optional.
  • qualifiers — extra qualifying data for a package, like an OS, architecture, a distro, etc. Optional and type-specific.
  • subpath — extra subpath within a package, relative to the package root. Optional.

🦋 EXAMPLES 🦋

more examples, the full-fat versions this time 💖

parse the given PURL string and return JSON, send the STDOUT to jq:

purl-tool pkg:cpan/GDT/URI-PackageURL@2.24 --json | jq

download the package from the repository using a Package URL string:

wget $(purl-tool pkg:cpan/GDT/URI-PackageURL@2.24 --download-url)

create a canonical Package URL string:

purl-tool --type cpan \
          --namespace GDT \
          --name URI-PackageURL \
          --version 2.24

display information about the provided PURL type (allowed components, repository, examples, etc.):

purl-tool --info rpm

👑 AUTHOR 👑

Giuseppe Di Terlizzi <https://metacpan.org/author/gdt> — the icon, the legend, the whole reason this page exists 🫶

Copyright © 2022-2025 Giuseppe Di Terlizzi <https://metacpan.org/author/gdt>

You may use and distribute this module according to the same terms that Perl is distributed under.

and that's the page, bestie 💅 the footer says perl v5.40.1, dated 2026-01-31, so now you have the version and the date, no cap 🌈 go forth and PURL, you've got this 🦋

📦 where this page comes from