<?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-2020</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>status</option></term>
				<listitem>
					<para>
						Display various information about the installed metadata and
						the metadata cache.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>get <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>Get a component by it's identifier.</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>s</option></term>
				<term><option>search <replaceable>TERM</replaceable></option></term>
				<listitem>
					<para>Search the AppStream component database 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>dump <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>
						Dump the XML description of a component with the given ID.
					</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 filetype 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>install <replaceable>ID</replaceable></option></term>
				<listitem>
					<para>
						Install a software component by its ID.
					</para>
					<para>
						This resolves the AppStream component ID to the package name which provides it and
						then calls the distribution's package manager to install the software.
					</para>
					<para>
						This feature is experimental.
					</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 <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> - Lesser than</para></listitem>
						<listitem><para><code>gt</code> - Greater than</para></listitem>
						<listitem><para><code>le</code> - Lesser 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>--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>pkcon (1).</para>
	</refsect1>
<refsect1>
<title>AUTHOR</title>
<para>
	This manual page was written by Matthias Klumpp <email>matthias@tenstral.net</email>.
</para>
</refsect1>
</refentry>
