Credentials & data cache¶
The first time you start the tool, there is a chance (unless you used something before that created it) you don't have the cached credentials located at
~/.zotero/cache/. You can either enter you API identifier and key through the
--key options or wait for the tool to ask for these. In both cases the values will be cached to
~/.zotero/cache/. This way, you won't have to re-enter them next time. From a security perspective, the only protection is that, once created, the credentials file immediately gets the read-write permissions only for your own user. So, the API key is NOT encrypted or hashed and thus resides in cleartext, only protected from reading by other users by the applied permissions.
Also, if the cache files do not exist, they will be downloaded from
pyzotero and saved in
~/.zotero/cache/. Four JSON files are cached:
collections.json: library's collections, downloaded using
items.json: library's items, downloaded using
Zotero.itemsmethod with parameter
Zotero.everything()in order to get everything at once.
notes.json: computed from the downloaded items.
Note that option
--reset-items (with command
reset) allows to only re-download items, and therefore also resets
There are two different ways to reset cached files:
--reset) general option (can be used with any command except
$ zotero-cli -r list [...] $ zotero-cli -r show [...]
resetcommand (this allows to use
$ zotero-cli reset -r $ zotero-cli reset --reset-items
In order to refine the returned data, multiple fields are computed by the tool:
authors: the list of
citations: the number of relations the item has to other items with a later date
editors: the list of
numAttachments: the number of child items with
numAuthors: the number of
numCreators: the number of
numEditors: the number of
numNotes: the number of child items with
numPages: the (corrected) number of pages, either got from the original or
references: the number of relations the item has to other items with an earlier date
year: the year coming from the
datetimeparsing of the
Additionaly, some fields are extracted from the (native)
comments: custom field for adding comments
results: custom field for mentioning results related to the item
what: custom field for a short description of what the item is about
zscc: number of Scholar citations, computed with the Zotero Google Scholar Citations plugin
A PageRank-based reference ranking algorithm is used to refine the data further for allowing to manipulate records by relevance.
rank: computed field aimed to rank references in order of relevance ; this uses an algorithm similar to Google's PageRank while weighting references in function of their year of publication (giving more importance to recent references, which cannot have as much citations as older references anyway given their recent nature)
Filtering and computed fields
Beware that filters (see next subsection) are applied BEFORE computing fields. Therefore, using the
rank field involves that only the filtered items were considered, which can drastically change results regarding their relevance.
Filter, sort and limit¶
For multiple commands, it is possible to filter fields, sort them and/or limit the number of records returned.
Filtering is done by using the
--filteroption with the following format:
[field]:[regex]; it is case-insensitive and applies to all commands but
For instance, let us assume a collection named "Bibliography", the following
regexvalue will filter items from this collection (given that no other collection starts with "
biblio", of course):
$ zotero-cli list title -f "collections:biblio"
Filters are AND-based. So, using multiple times the
--filterwill of course narrow the results. For instance, this will filter items from a collection named "Bibliography" published in 2020:
$ zotero-cli export title -f "collections:biblio" -f "year:2020"
There exists an exception to this regex-based filtering ; the
tagsfield. It relies on exact matches among the set of existing tags, which are collected at startup while parsing the items. Consequently, an error will be thrown if a bad tag is entered.
$ zotero-cli show title -f "tags:application" -f "tags:python"
Sorting is done by using the
--sortoption with the following format:
Any valid field can be used to sort records, including computed ones.
While filtering some particular fields, it is desirable to use operators to cover multiple values (e.g. with integers as for the
year field). For this purpose, the common comparison operators (
==) are available for use with the
--limit options for the following fields:
$ zotero-cli show title -f "year:<=2015" -f "numPages:>5"
$ zotero-cli show title -f "rank:>=1.5" -f "rank:<2.5"
$ zotero-cli show title -f "date:>Sep 2018"
Supported datetime formats
In order to filter datetimes, the following formats are supported:
%b %Y: e.g.
%B %Y: e.g.
%b %d %Y at %I:%M%p: e.g.
Jul 01 2015 at 02:01PM
%B %d, %Y, %H:%M:%S: e.g.
April 03, 2016, 13:15:00
List field values¶
It can be useful to inspect the values for a particular field, e.g. for correcting or normalizing some values. The
list command allows to list all the existing values from the library. It is also possible to list the available fields by simply using
$ zotero-cli list fields Fields ------ abstractNote accessDate archive archiveLocation [...]
Besides valid fields, attached files can also be listed by using
Any of the field names can then be used to list available values.
$ zotero-cli list publisher Publisher --------- - ACM [...] IEEE [...] Springer [...]
When the empty value also exists for the given field, it is listed as "
-". Beware that it can be filtered by using
$ zotero-cli show title -f "publisher:<empty>" Title ----- [...]
This can be very helpful to identify entries that have missing information.
List of values
Unless handled in the tool, fields that have lists of values (e.g.
tags with a list of semicolon-separted values) will be displayed as is. The following fields have this special handling for collecting distinct values:
Library items can be manipulated in different ways, as shown hereafter.
Counting items (filter only):
$ zotero-cli count -f "collections:biblio" -f "date:>Sep 2018" 123
Showing or exporting items (filter + sort + limit):
$ zotero-cli show year title numPages -f "collections:biblio" -f "date:>Sep 2018" -s date -l ">rank:2"
Use predefined queries¶
Some queries are predefined for the sake of simplicity.
$ zotero-cli show - --query "top-50-most-relevants" Year Title #Pages Type ---- ----- ------ ---- [...]
Use the "
-" field argument to use the list of fields to be displayed from the query. If other fields should be displayed, they can be entered instead of "
-" as normal ; this will override the fields from the query.
$ zotero-cli show year title --query "top-50-most-relevants" Year Title ---- ----- [...]
Moreover, using the
--sort options will override these of the query.
$ zotero-cli show year title --sort title --query "top-10-most-relevants" $ zotero-cli show year title --limit "title:5" --query "top-10-most-relevants"
The following queries are currently implemented:
top-10-most-relevants: returns the top-10 most relevant references, setting the
rankfield for ranking items according to a PageRank-like algorithm ; the displayed fields are
top-50-most-relevants: identical to the previous query, but with the top-50.
no-attachment: returns the list of items with no attachment ; useful for identifying references for which the related document was not attached yet, this only displays the
Library items can be marked as read or unread. By default, items are logically considered unread and are therefore displayed in bold. Once marked as read, they are not displayed in bold anymore.
$ zotero-cli mark --filter "key:QZR5QAIW" $ zotero-cli mark --query "top-10-most-relevants"
unread: by default, items are displayed in bold ; marking an item as read will make it display as normal
relevant: this allows to exclude a result from the output list of items
unignore: this allows to completely ignore an item, including in the ranking algorithm
NB: Markers are stored with other JSON files in the cache, that is, at