1APPSTREAMCLI(1)                  appstreamcli                  APPSTREAMCLI(1)
2
3
4

NAME

6       appstreamcli - Handle AppStream metadata formats and query AppStream
7       data
8

SYNOPSIS

10       appstreamcli [COMMAND]
11

DESCRIPTION

13       This manual page documents briefly the appstreamcli command.
14
15       appstreamcli is a small helper tool to work with AppStream metadata and
16       access the AppStream component index from the command-line. The
17       AppStream component index contains a list of all available software
18       components for your distribution, matched to their package names. It is
19       generated using AppStream XML or Debian DEP-11 data, which is provided
20       by your distributor.
21
22       For more information about the AppStream project and the other
23       components which are part of it, take a look at the AppStream pages at
24       Freedesktop.org[1].
25

OPTIONS

27       get ID
28           Get a component from the metadata pool by its identifier.
29
30       s, search TERM
31           Search the AppStream component pool for a given search term.
32
33       what-provides TYPE TERM
34           Return components which provide a given item. An item type can be
35           specified using the TYPE parameter, a value to search for has to be
36           supplied using the TERM parameter.
37
38           Examples:
39
40           Get components which handle the "text/xml" mediatype.
41
42           appstreamcli what-provides mediatype "text/xml"
43
44           Get component which provides the "libfoo.so.2" library.
45
46           appstreamcli what-provides lib libfoo.so.2
47
48       refresh, refresh-cache
49           Trigger a database refresh, if necessary. In case you want to force
50           the database to be rebuilt, supply the --force flag.
51
52           This command must be executed with root permission.
53
54       status
55           Display various information about the installed metadata and the
56           metadata cache.
57
58       os-info
59           Show information about the current operating system from the
60           metadata index. This requires the operating system to provide a
61           operating-system component for itself.
62
63       dump ID
64           Dump the complete XML descriptions of components with the given ID
65           that were found in the metadata pool.
66
67       validate FILES
68           Validate AppStream XML metadata for compliance with the
69           specification.
70
71           Both XML metadata types, upstream and distro XML, are handled. The
72           format type which should be validated is determined automatically.
73
74           The --pedantic flag triggers a more pedantic validation of the
75           file, including minor and style issues in the report.
76
77       validate-tree DIRECTORY
78           Validate AppStream XML metadata found in a file-tree.
79
80           This performs a standard validation of all found metadata, but also
81           checks for additional errors, like the presence of .desktop files
82           and validity of other additional metadata.
83
84       check-license LICENSE
85           Test a license string or license expression for validity and
86           display details about it.
87
88           This will check whether the license string is considered to be
89           valid for AppStream, and return a non-zero exit code if it is not.
90           The command will also display useful information like the canonical
91           ID of a license, whether it is suitable as license for AppStream
92           metadata, and whether the license is considered to be for Free and
93           Open Source software or proprietary software.
94
95           AppStream will consider any license as Free and Open Source that is
96           marked as suitable by either the Free Software Foundation (FSF),
97           Open Source Initiative (OSI) or explicit license list of the Debian
98           Free Software Guidelines (DFSG).
99
100       install ID
101           Install a software component by its ID using the package manager or
102           Flatpak.
103
104           This resolves the AppStream component ID to an installation
105           candidate and then calls either the native package manager or
106           Flatpak (if available) to install the component.
107
108       remove ID
109           Uninstall a software component by its ID using the package manager
110           or Flatpak.
111
112           This will uninstall software matching the selected ID using either
113           the native package manager or Flatpak (if available).
114
115       put FILE
116           Install a metadata file into the right directory on the current
117           machine.
118
119       compare-versions, vercmp VER1 [CMP] VER2
120           Compare two version numbers. If two version numbers are given as
121           parameters, the versions will be compared and the comparison result
122           will be printed to stdout.
123
124           If a version number, a comparison operator and another version
125           number are passed in as parameter, the result of the comparison
126           operation will be printed to stdout, and appstreamcli will exit
127           with a non-zero exit status in case the comparison failed. The
128           comparison operator can be one of the following:
129
130           •   eq - Equal to
131
132           •   ne - Not equal to
133
134           •   lt - Less than
135
136           •   gt - Greater than
137
138           •   le - Less than or equal to
139
140           •   ge - Greater than or equal to
141
142       new-template TYPE FILE
143           Create a metainfo file template to be used by software projects.
144           The --from-desktop option can be used to use a .desktop file as
145           template for generating the example file.
146
147           The generated files contain example entries which need to be filed
148           in with the actual desired values by the project author.
149
150           The first TYPE parameter is the name of an AppStream component
151           type. For a complete list check out the documentation[2] or the
152           help output of appstreamcli for this subcommand.
153
154       make-desktop-file MI_FILE DESKTOP_FILE
155           Create a XDG desktop-entry file from a metainfo file. If the
156           desktop-entry file specified in DESKTOP_FILE already exists, it
157           will get extended with the new information extracted from the
158           metainfo file. Otherwise a new file will be created.
159
160           This command will use the first binary mentioned in a provides tag
161           of the component for the Exec= field of the new desktop-entry file.
162           If this is not the desired behavior, the --exec flag can be used to
163           explicitly define a binary to launch. Other methods of launching
164           the application are currently not supported.
165
166           In order to generate a proper desktop-entry, this command assumes
167           that not only the minimally required tags for an AppStream
168           component are set, but also that it has an <icon/> tag of type
169           "stock" to describe the stock icon that should be used as well as a
170           <categories/> tag containing the categories the application should
171           be placed in.
172
173       news-to-metainfo NEWS_FILE MI_FILE [OUT_FILE]
174           This command converts a NEWS file as used by many open source
175           projects into the XML used by AppStream. Since NEWS files are free
176           text, a lot of heuristics will be applied to get reasonable
177           results. The converter can also read a YAML version of the
178           AppStream release description and convert it to XML as well. If the
179           metainfo file MI_FILE already exists, it will be augmented with the
180           new release entries, otherwise the release entries will be written
181           without any wrapping component. If [OUT_FILE] is specified, instead
182           of acting on MI_FILE the changed data will be written to the
183           particular file. If any of the output filenames is set to "-", the
184           output will instead be written to stdout.
185
186           The --format option can be used to enforce reading the input file
187           in a specific format ("text" or "yaml") in case the format
188           autodetection fails. The --limit option is used to limit the amount
189           of release entries written (the newest entries will always be
190           first).
191
192       metainfo-to-news MI_FILE NEWS_FILE
193           This command reverses the news-to-metainfo command and writes a
194           NEWS file as text or YAML using the XML contained in a metainfo
195           file. If NEWS_FILE is set to "-", the resulting data will be
196           written to stdout instead of to a file.
197
198           The --format option can be used to explicitly specify the output
199           format ("yaml" or "text"). If it is not set, appstreamcli will
200           guess which format is most suitable.
201
202       convert FILE1 FILE1
203           Converts AppStream XML metadata into its YAML representation and
204           vice versa.
205
206       compose
207           Composes an AppStream metadata catalog from a directory tree with
208           metainfo files. This command is only available if the
209           org.freedesktop.appstream.compose component is installed. See
210           appstreamcli-compose(1) for more information.
211
212       --details
213           Print out more information about a found component.
214
215       --no-color
216           Don't print colored output.
217
218       --no-net
219           Do not access the network when validating metadata.
220
221           The same effect can be achieved by setting the AS_VALIDATE_NONET
222           environment variable before running appstreamcli.
223
224       --version
225           Display the version number of appstreamcli
226

SEE ALSO

228       pkcon(1).
229

AUTHOR

231       This manual page was written by Matthias Klumpp
232       <matthias@tenstral.net>.
233
235       Copyright © 2012-2022 Matthias Klumpp
236

NOTES

238        1. Freedesktop.org
239           https://www.freedesktop.org/wiki/Distributions/AppStream/
240
241        2. the documentation
242           https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html
243
244
245
246AppStream                                                      APPSTREAMCLI(1)
Impressum