CLI-Connector for zotero
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Stefan Naumann c746e17dd9 README added qutebrowser section 1 year ago
src extractor: test added 1 year ago
tests test: fixed accessDate conflicts 1 year ago
LICENSE Initial commit 1 year ago
Makefile test: fixed accessDate conflicts 1 year ago README added qutebrowser section 1 year ago
pyproject.toml build pip project, config and cache directories 1 year ago
setup.cfg added pdfreader to setup.cfg 1 year ago
zotero-cli.ini.example create collections and (more or less empty) items in the library 1 year ago


CLI-Connector for zotero, can be used to insert entries into your Zotero library for example from inside qutebrowser or by shell. Tries to attach the PDF if it can be downloaded.


git clone
cd zotero-cli

make install
# or 
python -m build
pip install .


Zotero uses a configuration file in ~/.config/zotero-cli/config.ini. It looks much like the example-file. You'll need an API-key and the ID of the zotero library, as well as the type of the library (user or group).

Log into your Zotero-Account, then

  • Create an API-Key. There you'll also find your personal library-ID (use libtype user)
  • Groups, then hover over the group-name,<libID>/<name>. Then the libtype is group.


When the configuration is set up correctly, zotero-cli can be used by just passing an URL or path to a PDF (if there is metadata embedded). [url]

zotero-cli takes the following parameters:

usage: [-h] [--libid LIBID] [--libtype LIBTYPE] [--apikey APIKEY] [--config CONFIG]
                     [--library LIBRARY] [--debug] [--folder FOLDER] [--cache-dir CACHE_DIR] [--clear-cache]
                     [url ...]

positional arguments:
  url                   urls to add to zotero

optional arguments:
  -h, --help            show this help message and exit
  --libid LIBID         override the library ID from config
  --libtype LIBTYPE     override the library type from config
  --apikey APIKEY       override the api key from config
  --config CONFIG       use a different config file
  --library LIBRARY     choose a section in the config file (defaults to "default")
  --debug               set everything to very verbose
  --folder FOLDER       choose a folder (collection) to place new items in
  --cache-dir CACHE_DIR
                        choose a directory to download PDF files to for caching
  --clear-cache         clear the cache directory
  --silent              supress notifications


Zotero-cli was meant for the qutebrowser webbrowser. If you'd also like to use it inside the qutebrowser, it's configuration could look something like this (~/.config/qutebrowser/autoconfig.yml):

        ',Z': hint links spawn {hint-url}
        ',z': spawn {url}

Pressing ,z will try to insert the current URL into your zotero-library, ,Z will show link-hints. After selecting one of them, the selected one will be inserted.

Development and Bugs

If you find any bugs or libraries, which are not currently supported, please report them as an issue.

Starting development, you can have a look at the connector/ An Extractor is a piece of code, which starts from an input (most likely an URL or DOI) and creates a zotero-entry. E.g. the usenix-Extractor gets the website, finds the PDF link and extracts the metadata for the zotero-entry from the meta-tags in the HTML-code.

Adding an extractor is easy, first try to find out if the input is suitable for your extractor (isSupported), then extract an entry. Raise a CannotHandle exception if extraction does not work out. Please also add a few tests for your extractor (or the code behind it).