Zotero Project Manager (zpm)

Zotero Project Manager exports Zotero collections into clean, ordinary research folders. Zotero remains the source of truth: the project reads Zotero data and copies attachments outward without modifying the library, database, or original files.

Use the self-contained Zotero 9 plugin for interactive exports, or the Python CLI for batch operations, automation, verification, and safe pruning.

Choose an interface

Both interfaces produce the same managed workspace format. The plugin stays focused and conservative; the CLI provides explicit administrative controls.

Zotero 9 plugin

Exports run inside Zotero and do not require Python, Homebrew, pipx, or an executable path. Exports create and update local workspaces without launching other apps, running AppleScript, or uploading files.

Download the XPI from the latest GitHub release, then open Zotero → Tools → Plugins → gear menu → Install Plugin From File…. Existing installations can be upgraded in place.

Right-click a collection to use:

Export with zpm
    Export Collection
    Export Collection + Annotations
    Settings…

Settings control:

• the default export folder;
• whether non-PDF attachments such as README.md, text, images, and data are included;
• attachment filename ordering;
• separate, sidecar, or bundle annotation layout.

The first export asks for a destination if no valid default exists. Zotero can install future releases automatically when Update Add-ons Automatically is enabled in the Plugins gear menu; Check for Updates provides a manual check.

One workspace, your choice of app

Export a collection once and use its standard folder wherever you need it. For example, selecting My-AI → Agentic_AI exports to Agentic_AI/ and preserves its descendants inside that workspace. Re-exporting updates the same workspace. Choose Export Collection + Annotations to include annotations and child notes.

Open the target app yourself and select the exported files you want to use. zpm has no app-specific Send commands, stored notebook-link UI, automatic app indexing, uploading, or separate Notebook export format. The hidden .zpm/ directory is bookkeeping, not material to upload or import. You choose the files and compatible types in the destination app.

Stable 1.1.0 keeps the public 1.0.0 feature set and fixes Settings/Choose while adding concurrent-export protection. The experimental Gemini Notebook/DT4 preview integrations are not included; standard exports and naming/layout settings remain. Existing export folders (including old - NotebookLM folders), Google notebooks, DT4 records, and Zotero originals are not deleted or migrated. Old notebook-link preferences are left unused; the simplified plugin does not read or clear them. The earlier implementation remains in Git history.

The CLI no longer accepts --to, --notebook-url, --devonthink-group, --prepare-only, or --profile. Existing standard named projects still work. A saved project with export_profile = "notebooklm" is rejected with a migration message: review its output directory and layout, then remove that setting in its TOML config only if you want standard export. zpm never silently switches the project or rewrites the config on load.

See the Agentic_AI testing guide for installation and checks.

Python CLI

The CLI requires Python 3.11 or newer. Install it on macOS with Homebrew:

brew install sbilmis/tap/zpm

Or install the PyPI package with pipx:

brew install pipx
pipx install zotero-project-manager

Upgrade with brew upgrade zpm or pipx upgrade zotero-project-manager.

Quick start

List collections and export one recursively:

zpm list
zpm export "My-AI" --output ~/ResearchProjects

Include annotations and child notes:

zpm export "My-AI" --output ~/ResearchProjects --annotations

Preview changes, then safely prune files removed from Zotero:

zpm status "My-AI" --output ~/ResearchProjects --prune
zpm export "My-AI" --output ~/ResearchProjects --prune

Only manifest-owned files whose SHA-256 still matches are deleted.

Reusable projects and diagnostics

Save defaults or a named multi-collection project:

zpm config set --zotero-dir ~/Zotero --output ~/ResearchProjects
zpm project add ai "My-AI" "Claude" --annotations
zpm sync ai

Run a read-only readiness audit:

zpm doctor --output ~/ResearchProjects

Use zpm --help and zpm export --help for every command and option.

Workspace format

A typical export looks like this:

My-AI/
    Curie - 2024 - Paper title.pdf
    README.md
    Books/
        Author - 2023 - Book.pdf
    Annotations/
        Curie - 2024 - Paper title.md
    .zpm/
        manifest.json
        metadata.json
        INDEX.md
        export-summary.md

Generated control data lives under .zpm/, leaving ordinary project names such as README.md, INDEX.md, and metadata.json available for Zotero attachments.

The manifest supports incremental exports:

• unchanged files are left alone;
• new and changed attachments are copied;
• missing or removed attachments are recorded without silently deleting prior copies;
• identical files re-added under a new Zotero key are reconciled;
• root-level manifest v1–v4 workspaces migrate under .zpm/ after a successful export.

Annotations and layouts

Annotation export includes highlights, comments, page labels, tags, child notes, and available cached image or ink previews. It is opt-in because research notes may contain private material.

Choose one of three layouts:

• separate keeps generated Markdown under a parallel Annotations/ hierarchy;
• sidecar places paper.annotations.md beside each PDF;
• bundle creates one folder per paper containing the attachment and annotations.

The selected filename preset and layout are recorded in the manifest. Existing workspaces retain those settings to prevent surprising reorganizations.

Safety model

• Zotero files, attachments, and annotation caches are never modified.
• The CLI opens zotero.sqlite read-only with SQLite query-only protection.
• The plugin reads through Zotero's in-process APIs and does not open SQLite directly.
• Output paths inside the Zotero data directory are rejected.
• Unmanaged workspaces and conflicting user files are not adopted silently.
• Generated annotation and control files carry ownership markers.
• Full verification and pruning require explicit CLI options.

Keep independent backups of important research data.

Development

git clone https://github.com/sbilmis/zotero-project-manager.git
cd zotero-project-manager
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest
node --test zotero-plugin/tests/*.test.cjs

Build the release XPI and verify its update-feed entry with:

.venv/bin/python scripts/build_zotero_plugin.py

Install dist/zpm-zotero-1.1.0.xpi using Zotero's Tools → Plugins → gear → Install Plugin From File…, or use the XPI from the matching GitHub release. The installed Homebrew/pipx release does not change when this checkout changes; use .venv/bin/python -m zotero_project_manager to run the CLI from this checkout. For unpublished development versions only, pass --development to build without a published feed entry. Release builds and CI verify the exact update-feed hash.

See CONTRIBUTING.md, PUBLISHING.md, the plugin guide, and CHANGELOG.md for focused development and release details.

Zotero Project Manager is released under the MIT License.