CLI Reference¶

Auto-generated from source code.

zot¶

zot — Zotero CLI for Claude Code.

Quick start: zot search "attention mechanism" Search papers zot read ABC123 View paper details zot --json search "BERT" JSON output for AI

Usage:

zot [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--version`	boolean	Show the version and exit.	`False`
`--json`	boolean	Output as JSON (auto-enabled when stdout is not a TTY)	None
`--no-json`	boolean	Force human-readable output even when stdout is not a TTY	`False`
`--limit`	integer	Limit results	`50`
`--detail`	choice (`minimal` \| `standard` \| `full`)	Output detail level	`standard`
`--no-interaction`	boolean	Suppress interactive prompts for automation	`False`
`--verbose`	boolean	Verbose output	`False`
`--profile`	text	Config profile name	None
`--library`	text	Library: 'user' (default) or 'group:'	`user`
`--help`	boolean	Show this message and exit.	`False`

add¶

Add items to the Zotero library via DOI, URL, batch file, or PDF. MUTATES LIBRARY.

For --doi inputs, metadata (title, authors, journal, year, ...) is fetched from Crossref before posting so the created item is not a bare shell. Pass --no-resolve to skip the lookup. Requires API credentials (run 'zot config init' first).

Examples: zot add --doi "10.1038/s41586-023-06139-9" zot add --doi "10.1038/s41586-023-06139-9" --no-resolve # skip Crossref zot add --url "https://arxiv.org/abs/2301.00001" zot add --from-file dois.txt zot add --pdf paper.pdf zot add --pdf paper.pdf --doi "10.1234/override"

Usage:

zot add [OPTIONS]

Options:

Name	Type	Description	Default
`--doi`	text	DOI to add	None
`--url`	text	URL to add	None
`--from-file`	path	File with one DOI or URL per line	None
`--pdf`	path	PDF file to extract DOI from and attach (metadata not auto-resolved by API)	None
`--dry-run`	boolean	Preview what would be added without calling the API	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--no-resolve`	boolean	Skip Crossref DOI metadata lookup (faster, but creates a bare item)	`False`
`--help`	boolean	Show this message and exit.	`False`

ask¶

Retrieve a citation-keyed evidence pack to answer a question from a workspace.

Unlike workspace query (which dumps ranked chunks), ask returns evidence tagged with Zotero item keys plus answer instructions, so the calling agent can synthesize a grounded, cited answer. zot does not call an LLM itself.

Examples: zot ask "how does attention scale?" --workspace transformers zot --json ask "what dataset was used?" --workspace papers --evidence-k 8

Usage:

zot ask [OPTIONS] QUESTION

Options:

Name	Type	Description	Default
`--workspace`	text	Workspace to ask against	`Sentinel.UNSET`
`--evidence-k`	integer	Number of evidence chunks to retrieve (default: 12)	`12`
`--mode`	choice (`auto` \| `bm25` \| `semantic` \| `hybrid`)	Retrieval mode	`auto`
`--help`	boolean	Show this message and exit.	`False`

attach¶

Upload a file attachment to an existing Zotero item. MUTATES LIBRARY.

The default path uploads via the Zotero Web API, which stores the file in zotero.org cloud storage — it only appears in your local storage/ after the desktop syncs the file down (requires "Sync attachment files" enabled). Use --via-bridge to import through the running desktop instead, so the file is written to local storage immediately and cooperates with plugins that relocate attachments (e.g. zotero-attanger).

Examples: zot attach ABC123 --file paper.pdf zot attach ABC123 --file paper.pdf --via-bridge # store locally via desktop zot attach ABC123 --file ~/Downloads/supplement.pdf zot attach ABC123 --file paper.pdf --dry-run

Usage:

zot attach [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--file`	path	File to upload	`Sentinel.UNSET`
`--via-bridge`	boolean	Import through the running Zotero desktop (zot-cli-bridge plugin) so the file lands in local storage instead of cloud-only. Plays nice with zotero-attanger.	`False`
`--dry-run`	boolean	Preview the upload without calling the API	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--help`	boolean	Show this message and exit.	`False`

bridge¶

Package / check the zot-cli-bridge Zotero plugin (enables 'zot find-pdf').

Usage:

zot bridge [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

install¶

Build the bridge plugin .xpi to install via Zotero's plugin manager.

Zotero won't accept a CLI-sideloaded plugin, so this packages the .xpi and prints the two-click install steps.

Examples: zot bridge install zot bridge install --output ~/Desktop/zot-cli-bridge.xpi

Usage:

zot bridge install [OPTIONS]

Options:

Name	Type	Description	Default
`--output`	path	Where to write the .xpi (default: ~/.cache/zot/zot-cli-bridge.xpi)	None
`--help`	boolean	Show this message and exit.	`False`

status¶

Check whether Zotero + the bridge plugin are reachable.

Examples: zot bridge status zot --json bridge status

Usage:

zot bridge status [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

uninstall¶

Show how to remove the bridge plugin via Zotero's plugin manager.

Usage:

zot bridge uninstall [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

cite¶

Format a citation and copy to clipboard.

Examples: zot cite ABC123 APA style (default) zot cite ABC123 --style nature Nature style zot cite ABC123 --style vancouver Vancouver style zot cite ABC123 --no-copy Print without copying

Usage:

zot cite [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--style`	choice (`apa` \| `nature` \| `vancouver`)	Citation style (default: apa)	`apa`
`--no-copy`	boolean	Print only, do not copy to clipboard	`False`
`--help`	boolean	Show this message and exit.	`False`

collection¶

Manage Zotero collections.

Usage:

zot collection [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

create¶

Create a new collection.

Usage:

zot collection create [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--parent`	text	Parent collection key	None
`--help`	boolean	Show this message and exit.	`False`

delete¶

Delete a collection.

Usage:

zot collection delete [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Show what would be deleted without executing	`False`
`--help`	boolean	Show this message and exit.	`False`

items¶

List items in a collection.

Usage:

zot collection items [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

list¶

List all collections.

Usage:

zot collection list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

move¶

Move an item to a collection.

Usage:

zot collection move [OPTIONS] ITEM_KEY COLLECTION_KEY

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

rename¶

Rename a collection.

Usage:

zot collection rename [OPTIONS] KEY NEW_NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

reorganize¶

Batch create collections and move items based on a JSON plan file.

The plan file should be a JSON file with this structure:

{"collections": [{"name": "Topic A", "items": ["KEY1", "KEY2"]}, ...]}

Optional "parent" field creates subcollections.

Usage:

zot collection reorganize [OPTIONS] PLAN_FILE

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Preview the plan without executing	`False`
`--help`	boolean	Show this message and exit.	`False`

completions¶

Generate shell completion script.

Add the output to your shell profile to enable tab completions.

Examples: zot completions bash >> ~/.bashrc zot completions zsh >> ~/.zshrc zot completions fish > ~/.config/fish/completions/zot.fish

Usage:

zot completions [OPTIONS] {bash|zsh|fish}

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

config¶

Manage zot configuration.

Usage:

zot config [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

cache¶

Manage PDF text cache.

Usage:

zot config cache [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

clear¶

Clear the PDF text cache.

Usage:

zot config cache clear [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

list¶

List all cached PDF entries.

Usage:

zot config cache list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

stats¶

Show PDF cache statistics.

Usage:

zot config cache stats [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

init¶

Initialize configuration interactively.

Usage:

zot config init [OPTIONS]

Options:

Name	Type	Description	Default
`--config-path`	path	Config file path	None
`--data-dir`	text	Zotero data directory (auto-detected if not set)	None
`--library-id`	text	Zotero library ID	None
`--api-key`	text	Zotero API key	None
`--help`	boolean	Show this message and exit.	`False`

profile¶

Manage configuration profiles.

Usage:

zot config profile [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

list¶

List all profiles.

Usage:

zot config profile list [OPTIONS]

Options:

Name	Type	Description	Default
`--config-path`	path	N/A	None
`--help`	boolean	Show this message and exit.	`False`

set¶

Set the default profile.

Usage:

zot config profile set [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--config-path`	path	N/A	None
`--help`	boolean	Show this message and exit.	`False`

show¶

Show current configuration.

Usage:

zot config show [OPTIONS]

Options:

Name	Type	Description	Default
`--config-path`	path	Config file path	None
`--help`	boolean	Show this message and exit.	`False`

delete¶

Delete one or more items (move to trash). MUTATES LIBRARY.

Accepts multiple keys: zot delete KEY1 KEY2 KEY3

Usage:

zot delete [OPTIONS] KEYS...

Options:

Name	Type	Description	Default
`--yes`	boolean	Skip confirmation	`False`
`--dry-run`	boolean	Show what would be deleted without executing	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--help`	boolean	Show this message and exit.	`False`

duplicates¶

Find potential duplicate items in the library.

Examples: zot duplicates zot duplicates --by doi zot duplicates --by title --threshold 0.9 zot --json duplicates

Usage:

zot duplicates [OPTIONS]

Options:

Name	Type	Description	Default
`--by`	choice (`doi` \| `title` \| `both`)	Detection strategy (default: both)	`both`
`--threshold`	float	Title similarity threshold (default: 0.85)	`0.85`
`--limit`	integer	Limit results (overrides global --limit)	None
`--help`	boolean	Show this message and exit.	`False`

enrich¶

Write journal metrics into an item's Extra field. MUTATES LIBRARY.

Source-neutral — zot only writes the values you supply (inline --set or a --from-map table you maintain); it ships no journal data and calls no third-party API. Metrics go into a delimited  block in Extra, so re-running replaces just that block. Re-running is idempotent.

Examples: zot enrich ABCD1234 --set "SCI IF=5.8" --set "JCR=Q1" --dry-run zot enrich ABCD1234 --set "中科院分区=2区" zot enrich ABCD1234 EFGH5678 --from-map journals.toml zot enrich ABCD1234 --from-map journals.toml --set "JCR=Q1" # --set overrides the map

Usage:

zot enrich [OPTIONS] ITEM_KEYS...

Options:

Name	Type	Description	Default
`--set`	text	Metric as "Label=value" (repeatable), e.g. --set "SCI IF=5.8"	`Sentinel.UNSET`
`--from-map`	file	TOML table of journal name -> {metric: value}; applied by the item's journal	None
`--dry-run`	boolean	Preview the Extra changes without writing	`False`
`--help`	boolean	Show this message and exit.	`False`

export¶

Export citation in BibTeX, CSL-JSON, RIS, or raw JSON format.

Examples: zot export ABC123 BibTeX (default) zot export ABC123 --format csl-json CSL-JSON zot export ABC123 --format ris RIS zot export ABC123 --format json Raw JSON metadata

Usage:

zot export [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--format`	choice (`bibtex` \| `csl-json` \| `ris` \| `json`)	Export format	`bibtex`
`--help`	boolean	Show this message and exit.	`False`

find-pdf¶

Find and attach the full-text PDF for an item via Zotero desktop. MUTATES LIBRARY.

Requires Zotero desktop to be running with the zot-cli-bridge plugin installed (see extension/zot-cli-bridge/README.md). The plugin lets zot reuse the desktop's configured PDF resolvers AND the authenticated sessions / institutional proxies set up there — that's the part that the Zotero Web API alone cannot do, so this command is the only way to reach paywalled content from the CLI.

Examples: zot find-pdf ABCD1234 zot find-pdf ABCD1234 --dry-run # check bridge reachability zot find-pdf ABCD1234 --timeout 180 # give slow resolvers more time

Usage:

zot find-pdf [OPTIONS] ITEM_KEY

Options:

Name	Type	Description	Default
`--library-id`	integer	Override the Zotero library ID (default: user library on the desktop)	None
`--timeout`	float	Seconds to wait for resolvers to finish (default 120s)	`120.0`
`--dry-run`	boolean	Only verify the bridge is reachable; do not trigger Find Full Text	`False`
`--help`	boolean	Show this message and exit.	`False`

list¶

List items in the Zotero library.

Examples: zot list zot list --type journalArticle zot list --limit 10

Filter by Zotero collection (folder): zot collection list # show available collections zot list --collection "Machine Learning" --limit 10 # list within a collection

Usage:

zot list [OPTIONS]

Options:

Name	Type	Description	Default
`--collection`	text	Filter by Zotero collection (folder) name. Use 'zot collection list' to see available names.	None
`--type`	text	Filter by item type (e.g. journalArticle, book, preprint)	None
`--sort`	choice (`dateAdded` \| `dateModified` \| `title` \| `creator`)	Sort results by field	None
`--direction`	choice (`asc` \| `desc`)	Sort direction (default: desc)	`desc`
`--limit`	integer	Limit results (overrides global --limit)	None
`--stream`	boolean	Emit NDJSON (one item per line) for incremental processing	`False`
`--help`	boolean	Show this message and exit.	`False`

mcp¶

MCP server commands.

Usage:

zot mcp [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

serve¶

Start MCP server on stdio for use with LM Studio, Claude Desktop, etc.

Usage:

zot mcp serve [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

note¶

View or add notes for an item. --add MUTATES LIBRARY.

Examples: zot note ABC123 View notes zot note ABC123 --add "Key finding: ..." Add a note zot note ABC123 --add "..." --dry-run Preview addition zot --json note ABC123 JSON output

Usage:

zot note [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--add`	text	Add a new note	None
`--dry-run`	boolean	Preview the note addition without executing (only with --add)	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--help`	boolean	Show this message and exit.	`False`

open¶

Open the PDF or URL of a Zotero item in the default app.

Examples: zot open ABC123 Open PDF in default viewer zot open ABC123 --url Open DOI/URL in browser

Usage:

zot open [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--url`	boolean	Open the item URL in browser instead of PDF	`False`
`--help`	boolean	Show this message and exit.	`False`

orphans¶

Find / clean attachments whose stored file is missing from local storage.

Usage:

zot orphans [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

clean¶

Delete orphaned attachment records via the Web API. MUTATES LIBRARY.

By default only removes 'dead' orphans (no file anywhere). Pass --include-recoverable to also delete ones the server still holds (this discards the cloud copy too). Deletion goes through the Zotero Web API, so records that were never synced to the server return 'not_found' — remove those from the Zotero desktop instead.

Examples: zot orphans clean --dry-run zot orphans clean --yes zot orphans clean --include-recoverable --dry-run

Usage:

zot orphans clean [OPTIONS]

Options:

Name	Type	Description	Default
`--include-recoverable`	boolean	Also delete 'recoverable' orphans — DISCARDS the server copy too. Use with care.	`False`
`--yes`	boolean	Skip confirmation	`False`
`--dry-run`	boolean	Show what would be deleted without executing	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--help`	boolean	Show this message and exit.	`False`

list¶

List storage-backed attachments whose file is missing from local storage.

Each is classified: 'dead' (no copy anywhere — safe to remove with zot orphans clean), 'recoverable' (the server still has it — run a Zotero file-sync or open the item to download it), or 'unknown' (sync state unavailable).

Examples: zot orphans list zot orphans list --dead-only zot --json orphans list

Usage:

zot orphans list [OPTIONS]

Options:

Name	Type	Description	Default
`--dead-only`	boolean	Only show 'dead' orphans (no copy anywhere); hide recoverable ones	`False`
`--help`	boolean	Show this message and exit.	`False`

pdf¶

Extract text from the PDF attachment.

Full text is cached locally for fast repeated access.

Examples: zot pdf ABC123 Extract full text zot pdf ABC123 --pages 1-5 Extract pages 1-5 zot pdf ABC123 --outline List all headings as numbered outline zot pdf ABC123 --section 3 Extract content under 3rd heading zot pdf ABC123 --references Parsed reference list (needs GROBID) zot pdf ABC123 --tables Extract tables (needs pdfplumber) zot --json pdf ABC123 JSON output with metadata

Usage:

zot pdf [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--pages`	text	Page range, e.g. '1-5'	None
`--extractor`	text	PDF extractor to use (mineru, pymupdf). Defaults to auto-detect.	None
`--annotations`	boolean	Extract annotations (highlights, notes) instead of text	`False`
`--references`	boolean	Extract the parsed reference list (requires a running GROBID service)	`False`
`--tables`	boolean	Extract tables (requires the optional pdfplumber extractor)	`False`
`--outline`	boolean	Extract and list all headings as a numbered outline	`False`
`--section`	integer	Extract content under the N-th heading from outline	None
`--help`	boolean	Show this message and exit.	`False`

read¶

View item details (metadata, abstract, notes).

Examples: zot read ABC123 zot --json read ABC123 zot --detail full read ABC123

Usage:

zot read [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

recent¶

Show recently added or modified items.

Examples: zot recent Items added in last 7 days zot recent --days 30 Items added in last 30 days zot recent --limit 5 Limit to 5 results zot --json recent --days 14 JSON output

Usage:

zot recent [OPTIONS]

Options:

Name	Type	Description	Default
`--days`	integer	Number of days to look back (default: 7)	`7`
`--modified`	boolean	Sort by date modified instead of date added	`False`
`--limit`	integer	Limit results (overrides global --limit)	None
`--stream`	boolean	Emit NDJSON (one item per line) for incremental processing	`False`
`--help`	boolean	Show this message and exit.	`False`

relate¶

Find related items via shared tags, collections, or explicit relations.

Examples: zot relate ABC123 zot --json relate ABC123

Usage:

zot relate [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--limit`	integer	Limit results (overrides global --limit)	None
`--help`	boolean	Show this message and exit.	`False`

rename¶

Rename PDF attachment files from item metadata. MUTATES LIBRARY.

By default builds {journal}_{year}_{title}.pdf for each item's main PDF and ..._SI.pdf for supplementary PDFs. Non-PDF attachments (Excel, Word, web snapshots) are skipped. Requires Zotero desktop running with the zot-cli-bridge plugin v0.2.0+ (run zot bridge install).

Examples: zot rename ABCD1234 --dry-run # preview main + supp renames zot rename ABCD1234 EFGH5678 # rename several items zot rename ABCD1234 --main-only # skip supplementary PDFs zot rename ABCD1234 --template "{author}{year}" zot rename --attachment ATT0001 --name "X.pdf" # rename one file explicitly

Usage:

zot rename [OPTIONS] [ITEM_KEYS]...

Options:

Name	Type	Description	Default
`--template`	text	Filename template; tokens: {journal} {year} {title} (short title if set, else full) {fulltitle} {shorttitle} {author}	`{journal}_{year}_{title}`
`--main-only`	boolean	Rename only the main PDF (default also renames supplementary PDFs)	`False`
`--attachment`	text	Rename one specific attachment key (use with --name)	None
`--name`	text	Explicit new filename for --attachment (include the extension)	None
`--library-id`	integer	Override the Zotero library ID (default: user library)	None
`--force`	boolean	Overwrite if a file with the new name already exists	`False`
`--dry-run`	boolean	Preview the renames without changing any files	`False`
`--help`	boolean	Show this message and exit.	`False`

schema¶

Emit machine-readable schema for the CLI or one command.

Examples: zot schema # full tree zot schema search # schema for one command zot schema collection add # nested subcommand zot schema --diff prev.json # structural diff vs cached schema

Usage:

zot schema [OPTIONS] [COMMAND_PATH]...

Options:

Name	Type	Description	Default
`--diff`	file	Path to a previously-emitted schema. Output a structural diff against the current schema.	None
`--help`	boolean	Show this message and exit.	`False`

search¶

Search the Zotero library by title, author, tag, or full text.

Examples: zot search "transformer attention" zot search "GAN" --limit 5 zot --json search "single cell"

Filter by Zotero collection (folder): zot collection list # show available collections zot search "BERT" --collection "NLP" # search within "NLP" collection

Usage:

zot search [OPTIONS] QUERY

Options:

Name	Type	Description	Default
`--collection`	text	Filter by Zotero collection (folder) name. Use 'zot collection list' to see available names.	None
`--type`	text	Filter by item type (e.g. journalArticle, book, preprint)	None
`--sort`	choice (`dateAdded` \| `dateModified` \| `title` \| `creator`)	Sort results by field	None
`--direction`	choice (`asc` \| `desc`)	Sort direction (default: desc)	`desc`
`--limit`	integer	Limit results (overrides global --limit)	None
`--stream`	boolean	Emit NDJSON (one item per line) for incremental processing	`False`
`--help`	boolean	Show this message and exit.	`False`

stats¶

Show library statistics (items, PDFs, notes, types, collections, tags).

Examples: zot stats zot --json stats

Usage:

zot stats [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

summarize¶

Output a structured summary for Claude Code consumption.

Examples: zot summarize ABC123 zot --json summarize ABC123 zot --detail minimal summarize ABC123

Usage:

zot summarize [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

summarize-all¶

Export all items with key, title, and abstract for AI classification.

Examples: zot summarize-all Export all items zot summarize-all --limit 100 First 100 items zot summarize-all --offset 100 Skip first 100 (pagination)

Usage:

zot summarize-all [OPTIONS]

Options:

Name	Type	Description	Default
`--offset`	integer	Skip first N items (for pagination)	`0`
`--limit`	integer	Limit results (overrides global --limit)	None
`--help`	boolean	Show this message and exit.	`False`

tag¶

View or manage tags for one or more items.

View tags: zot tag KEY Batch add: zot tag KEY1 KEY2 KEY3 --add "newtag" Batch remove: zot tag KEY1 KEY2 --remove "oldtag"

Usage:

zot tag [OPTIONS] KEYS...

Options:

Name	Type	Description	Default
`--add`	text	Add a tag	None
`--remove`	text	Remove a tag	None
`--dry-run`	boolean	Show what would change without executing	`False`
`--help`	boolean	Show this message and exit.	`False`

trash¶

Manage trashed items (list, restore).

Usage:

zot trash [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

list¶

List items in the trash.

Examples: zot trash list zot trash list --limit 10 zot --json trash list

Usage:

zot trash list [OPTIONS]

Options:

Name	Type	Description	Default
`--limit`	integer	Limit results (overrides global --limit)	None
`--help`	boolean	Show this message and exit.	`False`

restore¶

Restore item(s) from trash. MUTATES LIBRARY.

Examples: zot trash restore ABC123 zot trash restore KEY1 KEY2 KEY3 zot trash restore ABC123 --dry-run

Usage:

zot trash restore [OPTIONS] KEYS...

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Show what would be restored without executing	`False`
`--help`	boolean	Show this message and exit.	`False`

update¶

Update item metadata fields via the Zotero API. MUTATES LIBRARY.

Examples: zot update ABC123 --title "New Title" zot update ABC123 --date "2025-01-01" zot update ABC123 --field volume=42 --field pages=1-10 zot update ABC123 --title "Title" --field abstractNote="New abstract" zot update ABC123 --title "New" --dry-run

Usage:

zot update [OPTIONS] KEY

Options:

Name	Type	Description	Default
`--title`	text	New title	None
`--date`	text	New date (e.g. 2025-01-01)	None
`--field`	text	Set field as key=value (repeatable)	`Sentinel.UNSET`
`--dry-run`	boolean	Preview the update without executing	`False`
`--idempotency-key`	text	Key so retries are safe; same key returns the original result	None
`--help`	boolean	Show this message and exit.	`False`

update-status¶

Check if preprints (arXiv, bioRxiv, medRxiv) have been formally published.

Uses the Semantic Scholar API to look up publication status. By default runs in dry-run mode — use --apply to update Zotero.

API key (optional, increases rate limit): --api-key KEY Pass directly export S2_API_KEY=KEY Official Semantic Scholar env var export SEMANTIC_SCHOLAR_API_KEY=KEY Alternative env var config.toml: semantic_scholar_api_key Set in zot config Apply at https://www.semanticscholar.org/product/api#api-key-form

Examples: zot update-status # check all preprints (dry-run) zot update-status --apply # update published items in Zotero zot update-status ABC123 # check a single item zot update-status --collection "NLP" # check items in a collection zot update-status --limit 10 # check at most 10 items

Usage:

zot update-status [OPTIONS] [KEY]

Options:

Name	Type	Description	Default
`--apply`	boolean	Actually update Zotero (default is dry-run)	`False`
`--api-key`	text	Semantic Scholar API key (or set S2_API_KEY env var)	None
`--collection`	text	Only check items in this collection	None
`--limit`	integer	Max items to check	None
`--help`	boolean	Show this message and exit.	`False`

workspace¶

Manage local workspaces for organizing papers by topic.

Usage:

zot workspace [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

add¶

Add items to a workspace by Zotero key.

Usage:

zot workspace add [OPTIONS] NAME KEYS...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

delete¶

Delete a workspace.

Usage:

zot workspace delete [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--yes`, `-y`	boolean	Skip confirmation	`False`
`--help`	boolean	Show this message and exit.	`False`

export¶

Export workspace items for external use.

Usage:

zot workspace export [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--format`	choice (`json` \| `markdown` \| `bibtex`)	Export format (default: markdown)	`markdown`
`--help`	boolean	Show this message and exit.	`False`

import¶

Bulk import items into a workspace from collection, tag, or search.

Usage:

zot workspace import [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--collection`	text	Import all items from a Zotero collection (name or key)	None
`--tag`	text	Import all items with this tag	None
`--search`	text	Import items matching a search query	None
`--help`	boolean	Show this message and exit.	`False`

index¶

Build RAG index for a workspace.

Usage:

zot workspace index [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--force`	boolean	Rebuild index from scratch	`False`
`--extractor`	text	PDF text extractor to use	None
`--skip-tag`	text	Skip PDF attachments carrying this tag (repeatable). Pass an empty value to disable.	`('skip-index',)`
`--help`	boolean	Show this message and exit.	`False`

list¶

List all workspaces.

Usage:

zot workspace list [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

new¶

Create a new workspace.

Usage:

zot workspace new [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--description`, `-d`	text	Workspace description (topic context)	``
`--help`	boolean	Show this message and exit.	`False`

query¶

Query workspace papers with natural language.

Usage:

zot workspace query [OPTIONS] QUESTION

Options:

Name	Type	Description	Default
`--workspace`	text	Workspace to query	`Sentinel.UNSET`
`--top-k`	integer	Number of results (default: 5)	`5`
`--mode`	choice (`auto` \| `bm25` \| `semantic` \| `hybrid`)	Retrieval mode	`auto`
`--help`	boolean	Show this message and exit.	`False`

remove¶

Remove items from a workspace by key.

Usage:

zot workspace remove [OPTIONS] NAME KEYS...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

search¶

Search items within a workspace by title, author, or abstract.

Usage:

zot workspace search [OPTIONS] QUERY

Options:

Name	Type	Description	Default
`--workspace`	text	Workspace to search	`Sentinel.UNSET`
`--help`	boolean	Show this message and exit.	`False`

show¶

Show items in a workspace.

Usage:

zot workspace show [OPTIONS] NAME

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`