'\" t
.\"     Title: appstreamcli
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 26 July,2012
.\"    Manual: appstreamcli
.\"    Source: AppStream
.\"  Language: English
.\"
.TH "APPSTREAMCLI" "1" "" "AppStream" "appstreamcli"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
appstreamcli \- Handle AppStream metadata formats and query AppStream data
.SH "SYNOPSIS"
.HP \w'\fBappstreamcli\fR\ 'u
\fBappstreamcli\fR [\fBCOMMAND\fR]
.SH "DESCRIPTION"
.PP
This manual page documents briefly the
\fBappstreamcli\fR
command\&.
.PP
\fBappstreamcli\fR
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\&.
.PP
For more information about the AppStream project and the other components which are part of it, take a look at the AppStream pages at
\m[blue]\fBFreedesktop\&.org\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "OPTIONS"
.PP
\fBstatus\fR
.RS 4
Display various information about the installed metadata and the metadata cache\&.
.RE
.PP
\fBget \fR\fB\fIID\fR\fR
.RS 4
Get a component by it\*(Aqs identifier\&.
.RE
.PP
\fBs\fR, \fBsearch \fR\fB\fITERM\fR\fR
.RS 4
Search the AppStream component database for a given search term\&.
.RE
.PP
\fBwhat\-provides \fR\fB\fITYPE\fR\fR\fB \fR\fB\fITERM\fR\fR
.RS 4
Return components which provide a given item\&. An item type can be specified using the
\fB\fITYPE\fR\fR
parameter, a value to search for has to be supplied using the
\fB\fITERM\fR\fR
parameter\&.
.sp
Examples:
.sp
Get components which handle the "text/xml" mediatype\&.
.sp
\fBappstreamcli\fR
what\-provides mediatype "text/xml"
.sp
Get component which provides the "libfoo\&.so\&.2" library\&.
.sp
\fBappstreamcli\fR
what\-provides lib libfoo\&.so\&.2
.RE
.PP
\fBrefresh\fR, \fBrefresh\-cache\fR
.RS 4
Trigger a database refresh, if necessary\&. In case you want to force the database to be rebuilt, supply the
\fB\-\-force\fR
flag\&.
.sp
This command must be executed with root permission\&.
.RE
.PP
\fBdump \fR\fB\fIID\fR\fR
.RS 4
Dump the XML description of a component with the given ID\&.
.RE
.PP
\fBvalidate \fR\fB\fIFILES\fR\fR
.RS 4
Validate AppStream XML metadata for compliance with the specification\&.
.sp
Both XML metadata types, upstream and distro XML, are handled\&. The filetype which should be validated is determined automatically\&.
.sp
The
\fB\-\-pedantic\fR
flag triggers a more pedantic validation of the file, including minor and style issues in the report\&.
.RE
.PP
\fBvalidate\-tree \fR\fB\fIDIRECTORY\fR\fR
.RS 4
Validate AppStream XML metadata found in a file\-tree\&.
.sp
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\&.
.RE
.PP
\fBinstall \fR\fB\fIID\fR\fR
.RS 4
Install a software component by its ID\&.
.sp
This resolves the AppStream component ID to the package name which provides it and then calls the distribution\*(Aqs package manager to install the software\&.
.sp
This feature is experimental\&.
.RE
.PP
\fBput \fR\fB\fIFILE\fR\fR
.RS 4
Install a metadata file into the right directory on the current machine\&.
.RE
.PP
\fBcompare\-versions \fR\fB\fIVER1\fR\fR\fB \fR\fB\fI[CMP]\fR\fR\fB \fR\fB\fIVER2\fR\fR
.RS 4
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\&.
.sp
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
\fBappstreamcli\fR
will exit with a non\-zero exit status in case the comparison failed\&. The comparison operator can be one of the following:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
eq
\- Equal to
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ne
\- Not equal to
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
lt
\- Lesser than
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
gt
\- Greater than
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
le
\- Lesser than or equal to
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ge
\- Greater than or equal to
.RE
.RE
.PP
\fBnew\-template \fR\fB\fITYPE\fR\fR\fB \fR\fB\fIFILE\fR\fR
.RS 4
Create a metainfo file template to be used by software projects\&. The
\fB\-\-from\-desktop\fR
option can be used to use a \&.desktop file as template for generating the example file\&.
.sp
The generated files contain example entries which need to be filed in with the actual desired values by the project author\&.
.sp
The first
\fITYPE\fR
parameter is the name of an AppStream component type\&. For a complete list check out
\m[blue]\fBthe documentation\fR\m[]\&\s-2\u[2]\d\s+2
or the help output of
\fBappstreamcli\fR
for this subcommand\&.
.RE
.PP
\fBmake\-desktop\-file \fR\fB\fIMI_FILE\fR\fR\fB \fR\fB\fIDESKTOP_FILE\fR\fR
.RS 4
Create a XDG desktop\-entry file from a metainfo file\&. If the desktop\-entry file specified in
\fIDESKTOP_FILE\fR
already exists, it will get extended with the new information extracted from the metainfo file\&. Otherwise a new file will be created\&.
.sp
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
\fB\-\-exec\fR
flag can be used to explicitly define a binary to launch\&. Other methods of launching the application are currently not supported\&.
.sp
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\&.
.RE
.PP
\fBnews\-to\-metainfo \fR\fB\fINEWS_FILE\fR\fR\fB \fR\fB\fIMI_FILE\fR\fR\fB \fR\fB\fI[OUT_FILE]\fR\fR
.RS 4
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
\fIMI_FILE\fR
already exists, it will be augmented with the new release entries, otherwise the release entries will be written without any wrapping component\&. If
\fI[OUT_FILE]\fR
is specified, instead of acting on
\fIMI_FILE\fR
the changed data will be written to the particular file\&. If any of the output filenames is set to "\-", the output will instead be written to stdout\&.
.sp
The
\fB\-\-format\fR
option can be used to enforce reading the input file in a specific format ("text" or "yaml") in case the format autodetection fails\&. The
\fB\-\-limit\fR
option is used to limit the amount of release entries written (the newest entries will always be first)\&.
.RE
.PP
\fBmetainfo\-to\-news \fR\fB\fIMI_FILE\fR\fR\fB \fR\fB\fINEWS_FILE\fR\fR
.RS 4
This command reverses the
\fBnews\-to\-metainfo\fR
command and writes a NEWS file as text or YAML using the XML contained in a metainfo file\&. If
\fINEWS_FILE\fR
is set to "\-", the resulting data will be written to stdout instead of to a file\&.
.sp
The
\fB\-\-format\fR
option can be used to explicitly specify the output format ("yaml" or "text")\&. If it is not set,
\fBappstreamcli\fR
will guess which format is most suitable\&.
.RE
.PP
\fB\-\-details\fR
.RS 4
Print out more information about a found component\&.
.RE
.PP
\fB\-\-no\-color\fR
.RS 4
Don\*(Aqt print colored output\&.
.RE
.PP
\fB\-\-no\-net\fR
.RS 4
Do not access the network when validating metadata\&.
.sp
The same effect can be achieved by setting the
\fBAS_VALIDATE_NONET\fR
environment variable before running
\fBappstreamcli\fR\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Display the version number of appstreamcli
.RE
.SH "SEE ALSO"
.PP
pkcon (1)\&.
.SH "AUTHOR"
.PP
This manual page was written by Matthias Klumpp
<matthias@tenstral\&.net>\&.
.SH "COPYRIGHT"
.br
Copyright \(co 2012-2021 Matthias Klumpp
.br
.SH "NOTES"
.IP " 1." 4
Freedesktop.org
.RS 4
\%https://www.freedesktop.org/wiki/Distributions/AppStream/
.RE
.IP " 2." 4
the documentation
.RS 4
\%https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html
.RE