APPSTREAMCLI-COMPOSE(1)

📦
version 1.2.2 · 8 versions
, in arch rolling, ubuntu stonking

💖 APPSTREAMCLI-COMPOSE — the manual page, but make it bestie-coded 💖

okay so we're talking about appstreamcli compose, from the appstreamcli compose manual, and honestly? she's iconic. sit down, grab a strawberry 🍓, we're gonna go through this together.

✨ NAME ✨

appstreamcli-compose — Compose AppStream metadata catalog from directory trees

like. she literally composes catalogs out of directory trees. main character energy fr. 👑

🌈 SYNOPSIS 🌈

appstreamcli compose [COMMAND]

🦋 DESCRIPTION 🦋

This manual page documents briefly the appstreamcli compose command. (yes, the manual page documents the thing, we're doing meta, we're doing inception, we're doing it 💅)

The appstreamcli compose tool is used to construct AppStream metadata catalogs from directory trees. But bestie, she does NOT stop there. She will also perform many related metadata generation actions, like resizing icons and screenshots, and merging in data from referenced desktop-entry files, plus translation status information. So basically she's doing the most, but in a slay way.

Which means: the tool gives you a fast way to test how the final processed metadata for an application that is shipped to users may look like. Observing the vibe before the vibe ships. 👀

It also gives you a way to easily generate AppStream data for projects which do not need a more complex data generator like appstream-generator. lowkey the chill option, no cap.

Heads up bestie: in order for the appstreamcli compose command to be available, you may need to install the optional compose module for appstreamcli first. She's not built in, she's a download. 😭

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] (link's at the bottom, i gotchu 🫶)

🎀 OPTIONS 🎀

SOURCE-DIRECTORIES

A list of directories to process needs to be provided as positional parameters. Data from all directories will be combined into one output namespace. so like, all the directories hold hands and become one. adorable. 🫶

  • --origin NAME — Set the AppStream data origin identifier. This can be a value like "debian-unstable-main" or "flathub". it's her government name, essentially. 💅
  • --result-root DIR — Sets the directory where all generated output that is deployed to a user's machine is exported to. If this parameter is not set and we only have one directory to process, we use that directory as default output path.

And listen: if both --data-dir and --icons-dir are set, --result-root is not necessary and no data will be written to that directory. so she can just vibe elsewhere. ✨

  • --data-dir DIR — Override the directory where the generated AppStream metadata catalog will be written to. Data will be written directly to this directory, and no supdirectories will be created (unlike when using --result-root to set an output location). no nesting, we keep it flat, we keep it simple 💅
  • --icons-dir DIR — Override the directory where the cached icons are exported to. icon dump, but make it intentional. 🎀
  • --hints-dir DIR — Set a directory where hints reported generated during metadata processing are saved to. If this parameter is not set, no HTML/YAML hint reports will be saved. so if you want the receipts, set the dir. 🧾
  • --media-dir DIR — If set, creates a directory with media content (icons, screenshots, ...) that can be served via a webserver. The metadata will be extended to include information about these remote media. remote media era. 🌐
  • --media-baseurl URL — The URL under which the contents of a directory set via --media-dir will be served. This value must be set if a media directory is created. not optional, bestie, she will not guess the URL. 😭
  • --prefix DIR — Set the default prefix that is used in the processed directories. If none is set explicitly, /usr is assumed. it's giving "we assumed /usr, and we were right." 🏠
  • --print-report MODE — Print the issue hints report (that gets exported as HTML and YAML document when --hints-dir was set) to the console in text form.

Various print modes are supported, and yes there's a whole spectrum:

  • on-error — only prints a short report if the run failed. this is the default, so if you didn't ask for anything, this is what you get. 🤷‍♀️
  • short — generates an abridged report that is always printed. she's yapping, but briefly.
  • full — results in a detailed report to be printed. she is telling you EVERYTHING. 💀
  • --no-partial-urls — If set, all URLs in the generated data will be absolute and media_baseurl will not be used. This makes changing the media mirror harder without regenerating all data and is generally not recommended, to increase flexibility. so like, don't? unless you must. it locks you in and we hate being locked in. 🙈
  • --icon-policy POLICY-STRING — Override the existing icon policy with a custom one. The icon policy sets how icons of different sizes should be dealt with. They can be:
    • in the icon cache only,
    • a remote icon in the media location,
    • or both cached and available in the remote location.

The icon-policy string is comprised of comma-separated %{size}x%{size}@%{scale}=%{state} statements. The size and scale are that of the respective icon, with the scale being allowed to be omitted if it is 1. The state can be one of remote, cached or cached-remote. 👑

By default, a policy of

48x48=cached,48x48@2=cached,64x64=cached,64x64@2=cached,128x128=cached-remote,128x128@2=cached-remote

is selected. that's the factory setting, she came out of the box gorgeous. 💖

  • --image-format FORMAT — Set the file format that generated icons and screenshots are stored in. Only jxl and png are permitted here, with jxl being the default.

JPEG-XL (jxl) yields considerably smaller files than PNG for the same visual quality, but can not be displayed by older AppStream clients. Select png if the generated metadata needs to be consumed by software that predates JPEG-XL support. backwards compatibility icon behavior fr.

Also: Icons are always stored losslessly, while screenshots are encoded with a sensible quality/size balance. icons get the full fidelity treatment, screenshots compromise a little for the sake of not shipping a 40MB png. 🍓

  • --allow-custom CUSTOM-KEY-NAMES — By default, all custom entries set in MetaInfo input data are removed. This flag allows one to whitelist custom keys to be propagated to the final catalog output data. The custom-key names should be provided as a comma-separated list. it's giving "invite list only" and honestly, fair. 💅
  • --components COMPONENT-IDs — Set a comma-separated list of AppStream component IDs that should be considered for the generated metadata. All components that exist in the input data but are not mentioned in this list will be ignored for the generated output. not on the list? not invited. 🙈
  • --no-color — Don't print colored output. sad beige terminal for sad beige workflows. 😔
  • --verbose — Display extra debugging information. she's talking in detail now. turn this on when you need the tea. 🍵
  • --version — Display the version number of appstreamcli compose. who is she? find out. ⭐

👀 SEE ALSO 👀

appstreamcli(1), appstream-generator(1).

🫶 AUTHOR 🫶

This manual page was written by Matthias Klumpp <matthias@tenstral.net>. king behavior honestly. 👑

Copyright © 2020-2026 Matthias Klumpp

🧚 NOTES 🧚

  1. Freedesktop.org https://www.freedesktop.org/wiki/Distributions/AppStream/

and that's the whole page bestie — no notes left behind, every flag accounted for, nothing skipped, nothing invented. 💖

this came to you from the AppStream corner of the world, as APPSTREAMCLI COMPOSE(1) — take care of her, she composes catalogs and she does it flawlessly. mwah. 💅✨🎀

📦 where this page comes from