<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY date        "<date>26 July,2012</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY package     "appstreamcli">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
	<refentryinfo>
	<title>appstreamcli</title>
	<copyright>
		<year>2012-2024</year>
		<holder>Matthias Klumpp</holder>
	</copyright>
	<productname>AppStream</productname>
	&date;
	</refentryinfo>

	<refmeta>
		<refentrytitle>appstreamcli</refentrytitle>
		<manvolnum>1</manvolnum>
	</refmeta>
	<refnamediv>
		<refname>&package;</refname>
		<refpurpose>Handle AppStream metadata formats and query AppStream data</refpurpose>
	</refnamediv>

       <refsynopsisdiv>
	       <cmdsynopsis>
		       <command>&package;</command>
		       <group>
			       <option>COMMAND</option>
		       </group>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			This manual page documents briefly the <command>&package;</command> command.
		</para>
		<para>
			<command>&package;</command> 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.
		</para>
		<para>
			For more information about the AppStream project and the other components which are part of it, take a look at
			the AppStream pages at <ulink url="https://www.freedesktop.org/wiki/Distributions/AppStream/">Freedesktop.org</ulink>.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<variablelist>
			<varlistentry>
				<term><option>get <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>Get a component from the metadata pool by its identifier.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>s</option></term>
				<term><option>search <replaceable>TERM</replaceable></option></term>
				<listitem>
					<para>Search the AppStream component pool for a given search term.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>what-provides <replaceable>TYPE</replaceable> <replaceable>TERM</replaceable></option></term>
				<listitem>
					<para>
						Return components which provide a given item. An item type can be specified using the
						<option><replaceable>TYPE</replaceable></option> parameter, a value to search for has to be
						supplied using the <option><replaceable>TERM</replaceable></option> parameter.
					</para>
					<para>Examples:</para>
					<para>
						Get components which handle the "text/xml" mediatype.
					</para>
					<para>
						<command>&package;</command> what-provides mediatype "text/xml"
					</para>
					<para>
						Get component which provides the "libfoo.so.2" library.
					</para>
					<para>
						<command>&package;</command> what-provides lib libfoo.so.2
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>refresh</option></term>
				<term><option>refresh-cache</option></term>
				<listitem>
					<para>
						Trigger a database refresh, if necessary.
						In case you want to force the database to be rebuilt, supply the <option>--force</option> flag.
					</para>
					<para>This command must be executed with root permission.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>status</option></term>
				<listitem>
					<para>
						Display various information about the installed metadata and
						the metadata cache.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>os-info</option></term>
				<listitem>
					<para>
						Show information about the current operating system from the metadata
						index.
						This requires the operating system to provide a <literal>operating-system</literal>
						component for itself.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>dump <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>
						Dump the complete XML descriptions of components with the given ID that were found in the
						metadata pool.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>validate <replaceable>FILES</replaceable></option></term>
				<listitem>
					<para>
						Validate AppStream XML metadata for compliance with the specification.
					</para>
					<para>
						Both XML metadata types, upstream and distro XML, are handled.
						The format type which should be validated is determined automatically.
					</para>
					<para>
						The <option>--pedantic</option> flag triggers a more pedantic
						validation of the file, including minor and style issues in the report.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>validate-tree <replaceable>DIRECTORY</replaceable></option></term>
				<listitem>
					<para>
						Validate AppStream XML metadata found in a file-tree.
					</para>
					<para>
						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.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>check-license <replaceable>LICENSE</replaceable></option></term>
				<listitem>
					<para>
						Test a license string or license expression for validity and display details about it.
					</para>
					<para>
						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.
					</para>
					<para>
						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).
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>install <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>
						Install a software component by its ID using the package manager or Flatpak.
					</para>
					<para>
						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.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>remove <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>
						Uninstall a software component by its ID using the package manager or Flatpak.
					</para>
					<para>
						This will uninstall software matching the selected ID using either the native
						package manager or Flatpak (if available).
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>put <replaceable>FILE</replaceable></option></term>
				<listitem>
					<para>
						Install a metadata file into the right directory on the current machine.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>compare-versions</option></term>
				<term><option>vercmp <replaceable>VER1</replaceable> <replaceable>[CMP]</replaceable> <replaceable>VER2</replaceable></option></term>
				<listitem>
					<para>
						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.
					</para>
					<para>
						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 <command>&package;</command> will exit with a non-zero exit status in case the comparison
						failed.
						The comparison operator can be one of the following:
					</para>
					<itemizedlist>
						<listitem><para><code>eq</code> - Equal to</para></listitem>
						<listitem><para><code>ne</code> - Not equal to</para></listitem>
						<listitem><para><code>lt</code> - Less than</para></listitem>
						<listitem><para><code>gt</code> - Greater than</para></listitem>
						<listitem><para><code>le</code> - Less than or equal to</para></listitem>
						<listitem><para><code>ge</code> - Greater than or equal to</para></listitem>
					</itemizedlist>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>new-template <replaceable>TYPE</replaceable> <replaceable>FILE</replaceable></option></term>
				<listitem>
					<para>
						Create a metainfo file template to be used by software projects. The <option>--from-desktop</option> option can be used
						to use a .desktop file as template for generating the example file.
					</para>
					<para>
						The generated files contain example entries which need to be filed in with the actual desired values by the project author.
					</para>
					<para>
						The first <replaceable>TYPE</replaceable> parameter is the name of an AppStream component type. For a complete list check out
						<ulink url="https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html">the documentation</ulink> or the help output
						of <command>&package;</command> for this subcommand.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>make-desktop-file <replaceable>MI_FILE</replaceable> <replaceable>DESKTOP_FILE</replaceable></option></term>
				<listitem>
					<para>
						Create a XDG desktop-entry file from a metainfo file.
						If the desktop-entry file specified in <replaceable>DESKTOP_FILE</replaceable> already exists, it will get extended with
						the new information extracted from the metainfo file. Otherwise a new file will be created.
					</para>
					<para>
						This command will use the first <literal>binary</literal> mentioned in a <literal>provides</literal> tag of the component
						for the <literal>Exec=</literal> field of the new desktop-entry file.
						If this is not the desired behavior, the <option>--exec</option> flag can be used
						to explicitly define a binary to launch. Other methods of launching the application are currently not supported.
					</para>
					<para>
						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 <code>&lt;icon/&gt;</code> tag of type "<literal>stock</literal>" to describe
						the stock icon that should be used as well as a <code>&lt;categories/&gt;</code> tag containing the categories the application should
						be placed in.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>news-to-metainfo <replaceable>NEWS_FILE</replaceable> <replaceable>MI_FILE</replaceable> <replaceable>[OUT_FILE]</replaceable></option></term>
				<listitem>
					<para>
						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.
						If the metainfo file <replaceable>MI_FILE</replaceable> already exists, it will be augmented with the new release entries, otherwise the release entries
						will be written without any wrapping component.
						If <replaceable>[OUT_FILE]</replaceable> is specified, instead of acting on <replaceable>MI_FILE</replaceable> the changed data will
						be written to the particular file. If any of the output filenames is set to "<code>-</code>", the output will instead be written to stdout.
					</para>
					<para>
						The <option>--format</option> option can be used to enforce reading the input file in a specific format ("text" or "yaml") in case the format autodetection fails.
						The <option>--limit</option> option is used to limit the amount of release entries written (the newest entries will always be first).
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>metainfo-to-news <replaceable>MI_FILE</replaceable> <replaceable>NEWS_FILE</replaceable></option></term>
				<listitem>
					<para>
						This command reverses the <option>news-to-metainfo</option> command and writes a NEWS file as text or YAML using the XML
						contained in a metainfo file. If <replaceable>NEWS_FILE</replaceable> is set to "<code>-</code>", the resulting data
						will be written to stdout instead of to a file.
					</para>
					<para>
						The <option>--format</option> option can be used to explicitly specify the output format ("yaml" or "text"). If it is not set,
						<command>&package;</command> will guess which format is most suitable.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>convert <replaceable>FILE1</replaceable> <replaceable>FILE1</replaceable></option></term>
				<listitem>
					<para>
						Converts AppStream XML metadata into its YAML representation and vice versa.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>compose</option></term>
				<listitem>
					<para>
						Composes an AppStream metadata catalog from a directory tree with metainfo files.
						This command is only available if the <code>org.freedesktop.appstream.compose</code>
						component is installed.
						See <citerefentry><refentrytitle>appstreamcli-compose</refentrytitle><manvolnum>1</manvolnum></citerefentry>
						for more information.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--details</option></term>
				<listitem>
					<para>Print out more information about a found component.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--no-color</option></term>
				<listitem>
					<para>Don't print colored output.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--no-net</option></term>
				<listitem>
					<para>Do not access the network when validating metadata.</para>
					<para>
						The same effect can be achieved by setting the <envar>AS_VALIDATE_NONET</envar> environment variable
						before running <command>&package;</command>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>--version</option></term>
				<listitem>
					<para>Display the version number of &package;</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</refsect1>

	<refsect1>
		<title>See Also</title>
		<para><citerefentry><refentrytitle>pkcon</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
	</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
	This manual page was written by Matthias Klumpp <email>matthias@tenstral.net</email>.
</para>
</refsect1>
</refentry>