CLI Reference
The pyzot provides a robust set of terminal commands under the zot binary.
This reference is automatically generated from the application's Click source code using mkdocs-click.
zot
zot — CLI for your Zotero library.
Usage:
zot [OPTIONS] COMMAND [ARGS]...
Options:
--db TEXT Path to zotero.sqlite
--library INTEGER Library ID (default: 1)
--format [table|json|csv] Output format
--no-color Disable colour output
--allow-write Allow write operations (ad-hoc override; or
set write.enabled=true in config).
--connector-url TEXT Zotero connector URL (default:
http://127.0.0.1:23119).
--require-zotero / --no-require-zotero
Fail if Zotero is not reachable (default:
require).
--help Show this message and exit.
add
Add items to your Zotero library via the connector.
When called with a single positional argument (no subcommand), automatically detects what kind of input it is (DOI, arXiv ID, PMID, ISBN, URL, citation string, or local file path) and dispatches to the right handler.
Examples:
zot add "10.1109/TPWRS.2023.1234567" # auto-detect DOI
zot add "2401.12345" # auto-detect arXiv
zot add "Zhang, J. et al. (2025) Beyond..." # auto-detect citation
zot add "/home/me/paper.pdf" # auto-detect file
zot add batch papers.txt # batch mode
Use zot add batch for scripted multi-item imports.
Usage:
zot add [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
batch
Process a file of inputs, one per line.
FILE may be - to read from stdin. Each line is passed through the
same auto-detect dispatcher as zot add "<anything>".
Lines that start with # or are blank are silently skipped.
After processing all lines a summary table is printed and, if any lines failed, the command exits with code 1.
Note: --jobs N (N > 1) is reserved for parallel resolver lookups in
a future release. Currently it is accepted but has no effect.
Example:
zot add batch papers.txt --collection "Smart Grid"
cat dois.txt | zot add batch - --tag imported
Usage:
zot add batch [OPTIONS] FILE
Options:
-c, --collection NAME Collection name applied to all items.
-t, --tag TEXT Tag to apply to all items (repeatable).
--dry-run Resolve and print what would be submitted
without making connector calls.
--on-duplicate [report|skip|force-add]
Behaviour when a duplicate is found.
[default: report]
-v, --verbose Print verbose HTTP request/response info.
--non-interactive Never prompt; fail/skip ambiguous citations.
--jobs INTEGER (Stub — reserved for parallel resolver
lookups in v0.3.0; currently no-op.)
[default: 1]
--help Show this message and exit.
cite
Add one or more items from free-text citation strings.
Usage:
zot add cite [OPTIONS] [CITATION_TEXT]
Options:
-f, --file PATH
--threshold INTEGER [default: 50]
--gap FLOAT [default: 1.4]
-c, --collection NAME Collection name to add the item to.
-t, --tag TEXT Tag to apply (repeatable).
--dry-run Print the JSON that would be POSTed without
making any request to the connector.
--on-duplicate [report|skip|force-add]
Behaviour when a duplicate is found.
[default: report]
-v, --verbose Print verbose HTTP request/response info.
--non-interactive Never prompt for citation disambiguation.
--help Show this message and exit.
status
Check whether Zotero is running and report the current target.
Prints reachability, selected collection, connector URL, and a hint about enabling write capability if not already enabled.
Usage:
zot add status [OPTIONS]
Options:
--help Show this message and exit.
attachments
Browse and open Zotero attachments.
Usage:
zot attachments [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
add
Attach an existing local file to an existing Zotero item.
Inserts the attachment directly into zotero.sqlite and copies the
file into <zotero-data-dir>/storage/<new-key>/.
Example:
zot attachments add ABCD1234 ~/Downloads/paper.pdf
Usage:
zot attachments add [OPTIONS] PARENT_KEY FILE_PATH
Options:
--title TEXT Display title (default: filename stem).
--source-url TEXT Source URL for provenance.
--help Show this message and exit.
fetch
Find and attach a PDF for an existing item using HTTP resolvers.
Tries DOI, item URL, and any custom resolvers in turn. The first successful PDF is attached as a child of the item.
Example:
zot attachments fetch 5UFZMSLU
Usage:
zot attachments fetch [OPTIONS] PARENT_KEY
Options:
--methods TEXT Comma-separated subset of resolvers to enable. [default:
doi,url,custom]
--help Show this message and exit.
fetch-all
Find PDFs for every library item that has a DOI/URL but no PDF.
Long-running. Honour --limit while testing. Items already with a PDF attachment are skipped. Rate-limiting is enforced per-domain by the pipeline internally.
Example:
zot attachments fetch-all --limit 20
Usage:
zot attachments fetch-all [OPTIONS]
Options:
--methods TEXT [default: doi,url,custom]
--limit INTEGER Cap total items processed.
--help Show this message and exit.
fetch-collection
Find PDFs for every item in a collection that doesn't already have one.
Example:
zot attachments fetch-collection "[Paper] LV_UG_Cable_Models_DSSE"
Usage:
zot attachments fetch-collection [OPTIONS] COLLECTION_NAME
Options:
--methods TEXT [default: doi,url,custom]
--include-with-pdf Also process items that already have a PDF (re-fetch).
--help Show this message and exit.
list
List all attachments.
Usage:
zot attachments list [OPTIONS]
Options:
--missing Only show missing files
--type TEXT Filter by content type (e.g. pdf)
--help Show this message and exit.
open
Open the first attachment with the system default application.
Usage:
zot attachments open [OPTIONS] ID_OR_KEY
Options:
--help Show this message and exit.
path
Print the resolved absolute path(s) for an item's attachments.
Usage:
zot attachments path [OPTIONS] ID_OR_KEY
Options:
--help Show this message and exit.
collections
Browse Zotero collections.
Usage:
zot collections [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
assign
Assign an existing item to a collection.
Does not remove the item from any existing collections (additive only).
Examples:
zot collection assign AB3CD7EF "Smart Grid"
zot collection assign AB3CD7EF "[Paper] LV_UG_Cable_Models_DSSE"
Usage:
zot collections assign [OPTIONS] ITEM_KEY COLLECTION_NAME
Options:
--help Show this message and exit.
items
List items in a collection.
Usage:
zot collections items [OPTIONS] ID_OR_NAME
Options:
-r, --recursive Include sub-collections
--type TEXT Filter to item type (e.g. journalArticle)
--help Show this message and exit.
list
Print the collection tree.
Usage:
zot collections list [OPTIONS]
Options:
--flat Flat list with IDs instead of tree view
--help Show this message and exit.
show
Show details for a collection.
Usage:
zot collections show [OPTIONS] ID_OR_NAME
Options:
--help Show this message and exit.
config
Manage pyzot settings.
Usage:
zot config [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
get
Print the value of KEY (section.key form, e.g. write.enabled).
Exits with code 1 if the key is not set.
Usage:
zot config get [OPTIONS] KEY
Options:
--help Show this message and exit.
library-auth
Store or display per-library authentication details for full-text retrieval.
Usage:
zot config library-auth [OPTIONS]
Options:
--library INTEGER Library ID (default: current)
--institution TEXT Institution/library provider name
--username TEXT Library login username
--password TEXT Library login password/token
--show Show current authentication details
--help Show this message and exit.
path
Print the pyzot home directory path.
Usage:
zot config path [OPTIONS]
Options:
--help Show this message and exit.
set
Set KEY to VALUE and persist to
Supported keys include write.enabled, write.connector_url, and any other dotted section.key value.
Usage:
zot config set [OPTIONS] KEY VALUE
Options:
--help Show this message and exit.
export
Export items to various formats.
Usage:
zot export [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
bib
Export items as BibTeX.
Usage:
zot export bib [OPTIONS]
Options:
-c, --collection TEXT Export a specific collection
-i, --item TEXT Export a specific item by ID or Key
--all Export entire library
-o, --output TEXT Output file (default: stdout)
--help Show this message and exit.
csv
Export items as CSV.
Usage:
zot export csv [OPTIONS]
Options:
-c, --collection TEXT Export a specific collection
-i, --item TEXT Export a specific item by ID or Key
--all Export entire library
-o, --output TEXT Output file (default: stdout)
--help Show this message and exit.
json
Export items as JSON.
Usage:
zot export json [OPTIONS]
Options:
-c, --collection TEXT Export a specific collection
-i, --item TEXT Export a specific item by ID or Key
--all Export entire library
-o, --output TEXT Output file (default: stdout)
--help Show this message and exit.
markdown
Export items as a Markdown report.
Usage:
zot export markdown [OPTIONS]
Options:
-c, --collection TEXT Export a specific collection
-i, --item TEXT Export a specific item by ID or Key
--all Export entire library
-o, --output TEXT Output file (default: stdout)
--notes Include notes sections
--help Show this message and exit.
items
Browse Zotero items.
Usage:
zot items [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
attachments
List attachments for an item.
Usage:
zot items attachments [OPTIONS] ID_OR_KEY
Options:
--help Show this message and exit.
fulltext
Retrieve full text for an item with network/auth/local fallback.
Usage:
zot items fulltext [OPTIONS] ID_OR_KEY
Options:
--max-chars INTEGER Maximum number of characters to print [default: 10000]
--offline Skip network/auth retrieval and only use local Zotero
data
--help Show this message and exit.
list
List items (paginated).
Usage:
zot items list [OPTIONS]
Options:
--type TEXT Filter by item type
--collection TEXT Filter by collection name/ID
--limit INTEGER Max items to show [default: 50]
--help Show this message and exit.
notes
Show notes attached to an item.
Usage:
zot items notes [OPTIONS] ID_OR_KEY
Options:
--help Show this message and exit.
show
Show full details for an item.
Usage:
zot items show [OPTIONS] ID_OR_KEY
Options:
--help Show this message and exit.
search
Search items across fields, authors, tags, DOIs, or years.
Examples: zot search "bayesian" --field title zot search --author "Numair" zot search "power flow" --type journalArticle zot search --doi 10.1038/example zot search --tag "machine-learning" zot search --year 2020-2024
Usage:
zot search [OPTIONS] [QUERY]
Options:
--field TEXT Restrict search to field(s) e.g. title, abstract
--author TEXT Search by author name (first or last, partial match)
--type TEXT Restrict to item type
--doi TEXT Search by DOI
--tag TEXT Search by tag
--year TEXT Year range e.g. 2020-2024 or 2022
--fulltext Use full-text index instead of field search
--help Show this message and exit.
stats
Library statistics dashboard.
Usage:
zot stats [OPTIONS] [COMMAND] [ARGS]...
Options:
--help Show this message and exit.
collections
Items per collection (top N).
Usage:
zot stats collections [OPTIONS]
Options:
--top INTEGER [default: 20]
--help Show this message and exit.
summary
Overall counts.
Usage:
zot stats summary [OPTIONS]
Options:
--help Show this message and exit.
tags
Top N tags by frequency.
Usage:
zot stats tags [OPTIONS]
Options:
--top INTEGER Number of top tags to show [default: 20]
--help Show this message and exit.
types
Items per item type.
Usage:
zot stats types [OPTIONS]
Options:
--help Show this message and exit.
years
Publication year histogram.
Usage:
zot stats years [OPTIONS]
Options:
--help Show this message and exit.