APPSTREAMCLI(1)

📦
version 1.2.2 · 8 versions
, in arch rolling

appstreamcli(1) 💅✨

okay so welcome to the appstreamcli manual page, bestie — this is the part where AppStream metadata actually makes sense. no cap, we're keeping every command, flag, value, and warning. 🫶

🌸 NAME 🌸

appstreamcli — Handle AppStream metadata formats and query AppStream data.

🦋 SYNOPSIS 🦋

appstreamcli [COMMAND]

✨ DESCRIPTION ✨

This manual page documents briefly the appstreamcli command. periodt. 💅

appstreamcli is a small helper tool to work with AppStream metadata and access the AppStream component index from the command-line. The AppStream component index contains a list of all available software components for your distribution, matched to their package names. It is generated using AppStream XML or Debian DEP-11 data, which is provided by your distributor. iykyk — the index is kinda the main character here. 👑

For more information about the AppStream project and the other components which are part of it, take a look at the AppStream pages at Freedesktop.org[1].

💅 OPTIONS 💅

okay so here's the whole menu, bestie — every command and flag, no skipping, fr fr.

  • get ID — Get a component from the metadata pool by its identifier. it's giving direct lookup energy. 🔍
  • s, search TERM — Search the AppStream component pool for a given search term. lowkey the classic search vibe. 🕵️‍♀️
  • what-provides TYPE TERM — Return components which provide a given item. An item type can be specified using the TYPE parameter, a value to search for has to be supplied using the TERM parameter.

Examples:

Get components which handle the "text/xml" mediatype.

appstreamcli what-provides mediatype "text/xml"

Get component which provides the "libfoo.so.2" library.

appstreamcli what-provides lib libfoo.so.2
  • list-reviews ID — List user reviews for the software component with the given ID, fetched from an online service compatible with the Open Desktop Ratings Service (ODRS).

The reviews are sorted by how helpful other users found them, with the amount of reviews shown at once limited via the --limit flag. Subsequent result pages can be requested using the --start flag, which sets the index of the first review to fetch.

By default, reviews matching the current system locale are preferred, use the --locale flag to select a different locale instead. The --server flag can be used to fetch reviews from a different ODRS-compatible server instead of the default one. review girlies, this one's for you. 🌟

  • refresh, refresh-cache — Trigger a database refresh, if necessary. In case you want to force the database to be rebuilt, supply the --force flag.
⚠️ This command must be executed with root permission.
  • status — Display various information about the installed metadata and the metadata cache. vibe check for your metadata setup. ✅
  • sysinfo — Show information about the current operating system from the metadata index. This requires the operating system to provide an operating-system component for itself.
  • dump ID — Dump the complete XML descriptions of components with the given ID that were found in the metadata pool. full XML unload, no crumbs. 🍪
  • validate FILES — Validate AppStream XML metadata for compliance with the specification.

Both XML metadata types, upstream and distro XML, are handled. The format type which should be validated is determined automatically.

The --pedantic flag triggers a more pedantic validation of the file, including minor and style issues in the report. strict mode activated. 💅

  • validate-tree DIRECTORY — Validate AppStream XML metadata found in a file-tree.

This performs a standard validation of all found metadata, but also checks for additional errors, like the presence of .desktop files and validity of other additional metadata.

  • check-license LICENSE — Test a license string or license expression for validity and display details about it.

This will check whether the license string is considered to be valid for AppStream, and return a non-zero exit code if it is not. The command will also display useful information like the canonical ID of a license, whether it is suitable as license for AppStream metadata, and whether the license is considered to be for Free and Open Source software or proprietary software.

AppStream will consider any license as Free and Open Source that is marked as suitable by either the Free Software Foundation (FSF), Open Source Initiative (OSI) or explicit license list of the Debian Free Software Guidelines (DFSG). license lore, but make it useful. 📜

  • install ID — Install a software component by its ID using the package manager or Flatpak.

This resolves the AppStream component ID to an installation candidate and then calls either the native package manager or Flatpak (if available) to install the component. slay, installation handled. 📦

  • remove ID — Uninstall a software component by its ID using the package manager or Flatpak.

This will uninstall software matching the selected ID using either the native package manager or Flatpak (if available).

  • put FILE — Install a metadata file into the right directory on the current machine. file goes in its little home. 🏠
  • compare-versions, vercmp VER1 [CMP] VER2 — Compare two version numbers. If two version numbers are given as parameters, the versions will be compared and the comparison result will be printed to stdout.

If a version number, a comparison operator and another version number are passed in as parameter, the result of the comparison operation will be printed to stdout, and appstreamcli will exit with a non-zero exit status in case the comparison failed. The comparison operator can be one of the following:

  • eq — Equal to
  • ne — Not equal to
  • lt — Less than
  • gt — Greater than
  • le — Less than or equal to
  • ge — Greater than or equal to
  • new-template TYPE FILE — Create a metainfo file template to be used by software projects. The --from-desktop option can be used to use a .desktop file as template for generating the example file.

The generated files contain example entries which need to be filled in with the actual desired values by the project author.

The first TYPE parameter is the name of an AppStream component type. For a complete list check out the documentation[2] or the help output of appstreamcli for this subcommand. template era, honestly. 🧚

  • make-desktop-file MI_FILE DESKTOP_FILE — Create a XDG desktop-entry file from a metainfo file. If the desktop-entry file specified in DESKTOP_FILE already exists, it will get extended with the new information extracted from the metainfo file. Otherwise a new file will be created.

This command will use the first binary mentioned in a provides tag of the component for the Exec= field of the new desktop-entry file. If this is not the desired behavior, the --exec flag can be used to explicitly define a binary to launch. Other methods of launching the application are currently not supported.

In order to generate a proper desktop-entry, this command assumes that not only the minimally required tags for an AppStream component are set, but also that it has an <icon/> tag of type "stock" to describe the stock icon that should be used as well as a <categories/> tag containing the categories the application should be placed in. desktop-entry glow-up. 🖥️

  • news-to-metainfo NEWS_FILE MI_FILE [OUT_FILE] — This command converts a NEWS file as used by many open source projects into the XML used by AppStream. Since NEWS files are free text, a lot of heuristics will be applied to get reasonable results. The converter can also read a YAML version of the AppStream release description and convert it to XML as well. The metainfo file MI_FILE must exist, and any release entries it already contains will be replaced with the ones generated from NEWS_FILE. If MI_FILE is set to "-", no metainfo file is read and only the generated release entries are written to stdout, without any wrapping component. If [OUT_FILE] is specified, instead of acting on MI_FILE the changed data will be written to the particular file. If it is set to "-", the output will instead be written to stdout.

Instead of a metainfo file, MI_FILE may also be a release metadata file, that is an XML file with releases as its root element as used for external release information. An existing file is recognized by its root element, so the name it carries does not matter. Since such a file contains nothing but the release entries that are about to be written, it is also created if it does not exist yet. This only applies to files named *.releases.xml, the names mandated by the specification; any other nonexistent file is an error.

The --format option can be used to enforce reading the input file in a specific format ("text", "markdown" or "yaml") in case the format autodetection fails. The --limit option is used to limit the amount of release entries written (the newest entries will always be first). The --translatable-count option limits the number of release descriptions that are marked as translatable, again counted from the newest entry. Descriptions of any older release will be marked with translate="no", so they do not end up in the translation template. important details, do not skip. 🫡

  • metainfo-to-news MI_FILE NEWS_FILE — This command reverses the news-to-metainfo command and writes a NEWS file as text or YAML using the XML contained in a metainfo file or in a release metadata file. If NEWS_FILE is set to "-", the resulting data will be written to stdout instead of to a file.

If MI_FILE is a metainfo file that keeps its release information in an external file (<releases type="external"/>), this command will fail and ask for the release metadata file to be passed instead, as the referenced data is not part of the metainfo file itself.

The --format option can be used to explicitly specify the output format ("yaml", "text" or "markdown"). If it is not set, appstreamcli will guess which format is most suitable based on the name of NEWS_FILE; it is therefore required when writing to stdout. reverse card, but for release notes. 🔁

  • convert FILE1 FILE1 — Converts AppStream XML metadata into its YAML representation and vice versa.
  • compose — Composes an AppStream metadata catalog from a directory tree with metainfo files. This command is only available if the org.freedesktop.appstream.compose component is installed. See appstreamcli-compose(1) for more information. composition era. 🧩
  • --details — Print out more information about a found component.
  • --no-color — Don't print colored output. ironic, but valid. 🌈
  • --no-net — Do not access the network when validating metadata.

The same effect can be achieved by setting the AS_VALIDATE_NONET environment variable before running appstreamcli.

  • --version — Display the version number of appstreamcli.

👀 SEE ALSO 👀

pkgcli(1).

💖 AUTHOR 💖

This page is a Matthias Klumpp original, bestie — written by the icon himself:

  • Matthias Klumpp <matthias@tenstral.net> — yes, that's the actual address, keep it exact 🫶

Copyright © 2012-2026 Matthias Klumpp

That's it, that's the whole thing — all the rights belong to him, no cap 👑

✨ NOTES ✨

Okay so there are exactly two footnotes and they're both links you're gonna wanna keep around, so here they are in all their glory 💅

  1. Freedesktop.org — like, the whole umbrella site, iykyk
https://www.freedesktop.org/wiki/Distributions/AppStream/
  1. the documentation — the actual metadata spec, go read it, it's giving essential 🌸
https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html
Heads up bestie: those URLs are literal — copy them character for character, don't let autocorrect or your terminal's fancy link-detection get creative with them 🙈

and that's the whole page, bestie!! 🦋 this one's served up fresh from AppStream and officially filed under APPSTREAMCLI(1) — go forth and appstreamcli your heart out, you absolute main character 💜✨

📦 where this page comes from