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
`--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.

Requires API credentials (run 'zot config init' first).

Examples: zot add --doi "10.1038/s41586-023-06139-9" 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
`--help`	boolean	Show this message and exit.	`False`

attach¶

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

Examples: zot attach ABC123 --file paper.pdf 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`
`--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`

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`

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`

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`

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`

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 --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
`--annotations`	boolean	Extract annotations (highlights, notes) instead of text	`False`
`--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`

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

Usage:

zot schema [OPTIONS] [COMMAND_PATH]...

Options:

Name	Type	Description	Default
`--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`
`--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`