Usage¶
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 --id
and --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 zotero.org
using pyzotero
and saved in ~/.zotero/cache/
. Four JSON files are cached:
collections.json
: library's collections, downloaded usingpyzotero
'sZotero.collections
method.items.json
: library's items, downloaded usingpyzotero
'sZotero.items
method with parameterZotero.everything()
in order to get everything at once.attachments.json
andnotes.json
: computed from the downloaded items.
Note that option --reset-items
(with command reset
) allows to only re-download items, and therefore also resets attachments.json
and notes.json
.
There are two different ways to reset cached files:
-
Use
-r
(--reset
) general option (can be used with any command exceptreset
)$ zotero-cli -r list [...] $ zotero-cli -r show [...]
-
Use the
reset
command (this allows to use--reset-items
)$ zotero-cli reset -r $ zotero-cli reset --reset-items
Computed fields¶
In order to refine the returned data, multiple fields are computed by the tool:
authors
: the list ofcreators
withcreatorType
equal toauthor
citations
: the number of relations the item has to other items with a later dateeditors
: the list ofcreators
withcreatorType
equal toeditor
numAttachments
: the number of child items withitemType
equal toattachment
numAuthors
: the number ofcreators
withcreatorType
equal toauthor
numCreators
: the number ofcreators
numEditors
: the number ofcreators
withcreatorType
equal toeditor
numNotes
: the number of child items withitemType
equal tonote
numPages
: the (corrected) number of pages, either got from the original orpages
fieldreferences
: the number of relations the item has to other items with an earlier dateyear
: the year coming from thedatetime
parsing of thedate
field
Additionaly, some fields are extracted from the (native) extra
field:
comments
: custom field for adding commentsresults
: custom field for mentioning results related to the itemwhat
: custom field for a short description of what the item is aboutzscc
: 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
-f
or--filter
option with the following format:[field]:[regex]
; it is case-insensitive and applies to all commands butreset
.For instance, let us assume a collection named "Bibliography", the following
regex
value 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
-f
/--filter
will 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
tags
field. 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
-s
or--sort
option with the following format:[field]
Any valid field can be used to sort records, including computed ones.
Comparison operators¶
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 (<
, >
, <=
, >=
and ==
) are available for use with the -f
/--filter
, -s
/--sort
and -l
/--limit
options for the following fields:
-
Integers:
citations
,numAttachments
,numAuthors
,numNotes
,numPages
,references
,year
,zscc
$ zotero-cli show title -f "year:<=2015" -f "numPages:>5"
-
Floats:
rank
$ zotero-cli show title -f "rank:>=1.5" -f "rank:<2.5"
-
Dates:
date
,dateAdded
,dateModified
$ zotero-cli show title -f "date:>Sep 2018"
Supported datetime formats
In order to filter datetimes, the following formats are supported:
%Y
: e.g.2020
%b %Y
: e.g.Oct 2019
%B %Y
: e.g.September 2018
%Y-%m-%dT%H:%M:%SZ
: e.g.2019-10-01T12:00:00Z
%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 fields
:
$ zotero-cli list fields
Fields
------
abstractNote
accessDate
archive
archiveLocation
[...]
Besides valid fields, attached files can also be listed by using attachments
.
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 -f "[field]:<empty>"
.
$ 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: authors
, creators
, editors
and tags
.
Count/Show/Export items¶
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
---- ----- ------ ----
[...]
Field argument
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 --limit
or --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 therank
field for ranking items according to a PageRank-like algorithm ; the displayed fields areYear
,Title
,#Pages
andType
.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 theTitle
.
Mark items¶
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"
Available markers
read
/unread
: by default, items are displayed in bold ; marking an item as read will make it display as normalirrelevant
/relevant
: this allows to exclude a result from the output list of itemsignore
/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 ~/.zotero/cache/marks.json
.