Metadata-Version: 2.4
Name: cli-anything-zotero
Version: 1.2.1
Summary: Zotero CLI and Python package for AI-assisted local library workflows.
Home-page: https://github.com/PiaoyangGuohai1/cli-anything-zotero
Author: cli-anything contributors
Author-email: 
License: Apache-2.0
Project-URL: Issues, https://github.com/PiaoyangGuohai1/cli-anything-zotero/issues
Project-URL: Documentation, https://github.com/PiaoyangGuohai1/cli-anything-zotero#installation
Project-URL: Changelog, https://github.com/PiaoyangGuohai1/cli-anything-zotero/releases
Keywords: zotero,cli,reference-manager,bibliography,ai-agents,ai,llm,academic,research-tools,bibtex,citation-manager,claude-code,cursor,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cli-anything-zotero

[![PyPI](https://img.shields.io/pypi/v/cli-anything-zotero?color=blue)](https://pypi.org/project/cli-anything-zotero/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License](https://img.shields.io/github/license/PiaoyangGuohai1/cli-anything-zotero)](LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/PiaoyangGuohai1/cli-anything-zotero)](https://github.com/PiaoyangGuohai1/cli-anything-zotero/releases)
[![GitHub stars](https://img.shields.io/github/stars/PiaoyangGuohai1/cli-anything-zotero)](https://github.com/PiaoyangGuohai1/cli-anything-zotero/stargazers)

**Let AI manage your Zotero library.**

[中文文档](docs/README_zh.md) | English | [Roadmap](docs/ROADMAP.md) | [TODO](docs/TODO.md) | [Commands](docs/COMMANDS.md)

> **MCP legacy notice:** `v0.9.5` is the final release with the `zotero-mcp` command and `cli-anything-zotero[mcp]` extra. New releases are CLI/SDK-first. Existing MCP users should pin `pip install "cli-anything-zotero[mcp]==0.9.5"` or use the `legacy/mcp` branch.

---

## For Non-Programmers

This tool is designed to be **used by AI, not memorized by you**. After a simple install (~3 minutes), just talk to your AI assistant in plain language:

> "Find papers about diabetes and kidney disease in my Zotero library"
>
> "Import this DOI into my CKM collection: 10.1038/s41586-024-07871-6"
>
> "Export all papers in my thesis collection as BibTeX"
>
> "Find PDFs for items in my review collection that are missing them"

**All you need to do:**
1. Follow the [Installation](#installation) steps below
2. Tell your AI assistant (Claude Code, Cursor, etc.) what you need
3. That's it

---

## What It Does

Built on [CLI-Anything](https://github.com/HKUDS/CLI-Anything) by [HKUDS](https://github.com/HKUDS), this tool gives AI agents full access to your local Zotero library through a **JS Bridge** — a lightweight Zotero plugin that exposes a privileged JavaScript endpoint.

**Prerequisite:** the **Zotero desktop app must be running**. This is intentional — we automate the local client (Connector, Local API, CLI Bridge), not a cloud-only API substitute.

**Key capabilities:**
- **Search & browse** — keyword search, full-text PDF search, collection tree, tags
- **Import** — from DOI, PMID, RIS/BibTeX files, or JSON
- **Export** — BibTeX, CSL-JSON, RIS, CSV, formatted citations
- **PDF management** — attach files, auto-find PDFs online, search annotations
- **Write operations** — update metadata, manage tags, add notes, trigger sync
- **DOCX citations** — turn `{{zotero:ITEMKEY}}` placeholders into static text or refreshable Zotero fields (see below)
- **Advanced** — execute arbitrary Zotero JS, semantic search with local embeddings, AI analysis

All write operations run locally through the JS Bridge — no API key or internet connection required.

### DOCX citations: static vs dynamic

AI-authored drafts should use placeholders such as `{{zotero:ITEMKEY}}` or
`{{zotero:KEY1,KEY2}}`, then convert them with the `docx` commands.

| Mode | Command | Output | Extra software |
|------|---------|--------|----------------|
| **Static** (default for simple finals) | `docx render-citations` or `docx cite --mode static` | Plain-text citations + static bibliography | **No.** Only `pip install` + JS Bridge + running Zotero (Local API). |
| **Dynamic** (refreshable fields) | `docx insert-citations` or `docx cite --mode dynamic` | Real Zotero fields in Word/LibreOffice + refreshable bibliography | **Yes — extra stack required** (see table below). |
| **Auto** | `docx cite --mode auto` | Picks dynamic if the stack is ready, else static | Same as dynamic when available |

**Dynamic mode is optional and is not installed by `pip` alone.** You also need:

| Requirement | Why |
|-------------|-----|
| Zotero Desktop (running) | Source library + word-processor integration |
| CLI Bridge plugin (`zotero-cli app install-plugin`) | Local privileged bridge used by conversion |
| [LibreOffice](https://www.libreoffice.org/) | Opens/saves the DOCX during field insertion |
| [Zotero LibreOffice plugin](https://www.zotero.org/support/word_processor_plugin_installation) | Creates refreshable citation/bibliography fields |

Check the machine before relying on dynamic mode:

```bash
zotero-cli --json docx doctor
```

If `doctor` reports missing LibreOffice / the LO add-in / Bridge, use **static**
mode (or install the missing pieces). On macOS the full dynamic path is tested
end-to-end; on Windows/Linux, `doctor` works but auto open/save may still need
manual LibreOffice interaction until verified.

One-shot when you are unsure:

```bash
zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force
```

---

## CLI-First Usage

`cli-anything-zotero` is now maintained as a CLI/SDK-first tool. The primary interface is the `zotero-cli` shell command, which works well for Codex, Claude Code, Cursor, shell scripts, and other agents that can run terminal commands.

For legacy MCP users, install the frozen MCP release explicitly:

```bash
pip install "cli-anything-zotero[mcp]==0.9.5"
```

The `legacy/mcp` branch and the `v0.9.5` release remain available, but MCP receives no new feature maintenance after that line.

---

## Installation

**Prerequisites:** Python 3.10+, Zotero 7/8/9 (running).

### Step 1: Install the package

```bash
pip install cli-anything-zotero
```

This installs the `zotero-cli` command. The old `cli-anything-zotero` command remains as a compatibility alias.

### Step 2: Install the JS Bridge Plugin (one-time, both modes)

```bash
zotero-cli app install-plugin
```

First install requires manual steps in Zotero:
1. The command generates a `.xpi` file and prints its path
2. In Zotero: **Tools → Plugins → gear icon → Install Plugin From File...**
3. Select the `.xpi` file, then **restart Zotero**

> After the first install, future upgrades via `app install-plugin` are automatic.

For existing users upgrading to the dynamic DOCX citation workflow, update both
the Python package and the Zotero bridge plugin:

```bash
python -m pip install -U cli-anything-zotero
zotero-cli app install-plugin
# restart Zotero
zotero-cli app plugin-status
zotero-cli docx doctor
```

### Step 3: Set up your AI client

No client-specific setup is required. Tell your AI assistant that `zotero-cli` is available; it can run `zotero-cli --help` to discover commands.

Verify it works:

```bash
zotero-cli app ping
zotero-cli js "return Zotero.version"
```

### Troubleshooting

| Problem | Solution |
|---------|----------|
| `Cannot resolve Zotero profile directory` | Launch Zotero at least once first |
| Plugin not appearing | Restart Zotero after installing the `.xpi` |
| `endpoint_active: false` | Plugin failed to load — reinstall via Zotero UI |
| Windows: `pip` not recognized | Close and reopen PowerShell after installing Python |

---

## Usage (CLI Mode)

**Search & Browse**
```bash
zotero-cli item find "machine learning"
zotero-cli item search-fulltext "CRISPR"
zotero-cli collection tree
```

**Import**
```bash
# Preferred agent ingest
zotero-cli --json add doi "10.1038/s41586-024-07871-6" --tag "review" --fetch-pdf
zotero-cli --json add arxiv 2602.02093 --collection COLLECTION_KEY
zotero-cli --json add file ./paper.pdf
zotero-cli --json add bibtex ./refs.bib --collection COLLECTION_KEY

# Lower-level import still available
zotero-cli import doi "10.1038/s41586-024-07871-6" --no-translator
zotero-cli --json item fetch-pdf ITEM_KEY --sources zotero,unpaywall,arxiv
zotero-cli --json collection fetch-pdfs COLLECTION_KEY --limit 20 --jsonl-progress

# DOCX one-shot citations
zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

# Audit recent write ops
zotero-cli --json audit tail --limit 20
```

**Read & Export**
```bash
zotero-cli item get ITEM_KEY
zotero-cli item find "keyword" --scope fields
zotero-cli item export ITEM_KEY --format bibtex
zotero-cli export bib --items KEY1,KEY2 --output refs.bib
zotero-cli item citation ITEM_KEY
zotero-cli item context ITEM_KEY              # LLM-ready context
zotero-cli docx inspect-citations draft.docx  # detect Zotero/EndNote/static citation fields
zotero-cli docx validate-placeholders draft.docx
zotero-cli docx render-citations draft.docx --output draft-static.docx --force
zotero-cli docx doctor
zotero-cli docx insert-citations draft.docx --output draft-zotero.docx --force
```

For AI-authored DOCX workflows, use Zotero-bound placeholders such as
`{{zotero:ITEMKEY}}` or `{{zotero:KEY1,KEY2}}`, then choose the final output
mode (details and **extra software requirements** are under
[DOCX citations: static vs dynamic](#docx-citations-static-vs-dynamic)):

- Static citations: `docx render-citations` replaces placeholders with ordinary citation text and appends a static bibliography. Easiest path; **no LibreOffice**. Cannot be refreshed by the Zotero word processor plugin.
- Dynamic citations: `docx insert-citations` converts placeholders into real Zotero/LibreOffice fields and creates or updates a refreshable bibliography field. Needs **LibreOffice + Zotero LO add-in + Bridge** on top of Zotero Desktop.

AI agents should ask the user which mode they want when the request is
ambiguous. If the user only wants a simple final DOCX and has not installed
LibreOffice, prefer static citations. Always run `docx doctor` before promising
dynamic conversion.

Recommended AI protocol:

1. `zotero-cli --json docx validate-placeholders <input.docx>`
2. If the user wants editable references / refresh support:
   - `zotero-cli --json docx doctor`
   - `zotero-cli --json docx insert-citations <input.docx> --output <final.docx> --force`
   - If conversion fails, report the failing layer from `doctor` and ask the user for next steps.
3. If the user wants static output or dynamic is unavailable:
   - `zotero-cli --json docx render-citations <input.docx> --output <final.docx> --force`

Keep these files only as handoff artifacts:
- Placeholder draft (`<input.docx>`)
- Final converted draft (`<final.docx>`)
- No intermediate DOCX should be exposed unless `--debug-dir` is explicitly requested.

Platform support for this optional workflow:
- macOS: tested end-to-end with automatic open, conversion, save, and Word-compatible DOCX output.
- Windows/Linux: the base CLI works, and `docx doctor` can report missing dependencies. Full automatic LibreOffice open/save for dynamic DOCX citations still needs real Windows/Linux desktop validation; users may need to open or save the LibreOffice document manually until platform automation is verified.

`validate-placeholders`, `zoterify-preflight`, and `zoterify-probe` are
diagnostics for setup or failure cases. Add `--debug-dir` only when you want
JSON artifacts for troubleshooting.
`docx prepare-zotero-import` exists only as an experimental debugging command;
it is not a supported writing workflow after Zotero 9 + LibreOffice testing.
`docx insert-citations` and `docx render-citations` are the two supported outputs
for AI-authored citation insertion.
`item citation` and `item bibliography` render static previews; they are not
refreshable Word/LibreOffice Zotero fields. BIB export is a separate export
feature and is not part of the DOCX writing workflow.

**Write & Manage**
```bash
zotero-cli item update KEY --field title="New Title"
zotero-cli item tag KEY --add "important"
zotero-cli item attach KEY ./paper.pdf
zotero-cli item find-pdf KEY
zotero-cli note add KEY --text "My note"
zotero-cli sync
```

**Advanced**
```bash
zotero-cli item search-annotations "risk"
zotero-cli item annotations KEY
zotero-cli item metrics KEY                   # NIH citation metrics
zotero-cli collection stats COLLECTION_KEY
zotero-cli js "return await Zotero.Items.getAll(1).then(i => i.length)"
```

Full command reference: **[docs/COMMANDS.md](docs/COMMANDS.md)**

---

## Optional Features

These require extra services. Everything else works without them.

### Semantic Search

Any OpenAI-compatible `/v1/embeddings` endpoint ([Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), OpenAI, etc.).

```bash
zotero-cli item build-index                            # one-time
zotero-cli item semantic-search "cardiovascular risk"
zotero-cli item similar ITEM_KEY
```

| Variable | Default | Description |
|----------|---------|-------------|
| `ZOTERO_EMBED_API` | `http://127.0.0.1:8080/v1/embeddings` | Embedding API endpoint |
| `ZOTERO_EMBED_MODEL` | `nomic-embed-text` | Model name |
| `ZOTERO_EMBED_KEY` | *(empty)* | API key (if needed) |

### AI Analysis

```bash
export OPENAI_API_KEY=sk-...
zotero-cli item analyze ITEM_KEY --question "What are the main findings?"
```

---

## Legacy MCP Users

MCP support is frozen at `v0.9.5`. To keep using the previous MCP server, install:

```bash
pip install "cli-anything-zotero[mcp]==0.9.5"
```

You can also use the `legacy/mcp` branch for source installs. Starting with `v1.0.0`, the maintained package installs only CLI/SDK surfaces and no longer provides the `zotero-mcp` command.

## Related Projects

There are several great tools in the Zotero ecosystem. Each has different strengths depending on your use case:

| | **cli-anything-zotero** | [zotero-mcp](https://github.com/54yyyu/zotero-mcp) | [zotero-cli-cc](https://github.com/Agents365-ai/zotero-cli-cc) | [pyzotero-cli](https://github.com/chriscarrollsmith/pyzotero-cli) |
|---|---|---|---|---|
| **Approach** | Local JS Bridge | Web API + MCP | Web API + CLI | Web API + CLI |
| **Best for** | Local-first, full control | MCP-native workflows | Agent-driven research | Scripting & automation |
| **Write ops** | Local (no API key) | Via Web API | Via Web API | Via Web API |
| **MCP support** | Legacy via v0.9.5 | Yes | 45 tools | No |
| **Terminal CLI** | Yes | No | Yes | Yes |
| **Zotero JS access** | Yes | No | No | No |
| **License** | Apache 2.0 | MIT | CC BY-NC 4.0 | MIT |

---

## License

[Apache 2.0](LICENSE)
