pyzotero-cli

pyzotero-cli is a powerful command-line interface (CLI) for interacting with your Zotero library. It acts as a wrapper around the excellent pyzotero library, exposing its rich functionality directly to your terminal.

This tool is designed for users who prefer a command-line workflow, for scripting Zotero interactions, or for integration with other tools and AI agents that can leverage shell commands. Example "Rules for AI" to instruct your AI agent (e.g., in Cline or Cursor) how to use this tool are available in the /rules_for_ai folder in the Github repository.

Features

• Comprehensive Zotero API Coverage: Manage items, collections, tags, attachments, saved searches, full-text content, and groups.
• Flexible Configuration:
  • Support for multiple profiles.
  • Configuration via interactive setup, environment variables, or direct CLI flags.
  • Option to use a local Zotero instance (read-only).
• Multiple Output Formats: Get data as JSON (default), YAML, or user-friendly tables. Also supports keys output for easy piping.
• Rich Querying Capabilities:
  • Pagination (--limit, --start).
  • Sorting (--sort, --direction).
  • Filtering (--query, --filter-tag, --filter-item-type).
  • Versioning/Syncing (--since).
• Full CRUD Operations: Create, Read, Update, and Delete various Zotero entities.
• File Management: Download and upload attachments.
• Utility Commands: Access API key info, library versions, item type definitions, and more.

Why pyzotero-cli?

• Automation & Scripting: Easily integrate Zotero operations into your shell scripts and automated workflows.
• Terminal Power Users: Manage your Zotero library without leaving the command line.
• AI Agent Integration: Designed to be easily consumable by AI systems with Bash/shell execution capabilities.
• Focused Interface: Provides direct access to pyzotero features in a command-line paradigm.

Installation

pyzotero-cli requires Python 3.10 or higher. You can install it in your current Python environment using pip:

pip install pyzotero-cli -U # -g for global install

For global installation, better practice is to download and install uv and then use uv tool install to install into uv's persistent managed tool environment:

# Install latest version of pyzotero-cli as a persistent tool
uv tool install pyzotero-cli -U

# Ensure uv's bin directory is in your PATH (if needed)
uv tool update-shell

# Now the `zot` command is available directly
zot --help

You can also use uvx to run the CLI tool in a temporary environment without permanently installing it:

# Run the zot CLI in a temporary isolated environment
uvx --from pyzotero-cli zot --help

Configuration

Before you can use pyzotero-cli to interact with your Zotero library (unless using the --local flag for a local read-only Zotero instance), you need to configure it with your Zotero API key and library details.

The easiest way to get started is with the interactive setup:

zot configure setup

This will guide you through setting up a default profile, asking for:

• Zotero Library ID: Your Zotero User ID (for personal libraries) or Group ID.
• Library Type: user or group.
• Zotero API Key: Generate one from your Zotero account settings (Feeds/API page).
• Use local Zotero instance: Whether to connect to a running Zotero desktop client locally (read-only mode, not recommended!).
• Locale: Defaults to en-US.

Configuration is stored in ~/.config/zotcli/config.ini.

Profiles

You can manage multiple configurations using profiles:

# Set up a new profile named 'work_group'
zot configure setup --profile work_group

# List available profiles
zot configure list-profiles

# Set the default active profile
zot configure current-profile work_group

# Use a specific profile for a single command
zot --profile work_group items list

Configuration Precedence

The CLI respects the following order of precedence for configuration settings:

1. Command-line flags (e.g., --api-key, --library-id).
2. Environment variables (e.g., ZOTERO_API_KEY, ZOTERO_LIBRARY_ID, ZOTERO_LIBRARY_TYPE).
3. Active profile in ~/.config/zotcli/config.ini.

Basic Usage

Once configured, you can interact with your library using the zot command.

# List the 5 most recently modified items (default JSON output)
zot items list --limit 5

# Get details for a specific item (replace <ITEM_KEY> with an actual key)
zot items get <ITEM_KEY>

# List top-level collections in a table format
zot collections list --top --output table

# Get help for the 'items' command group
zot items --help

# Get help for a specific subcommand
zot items create --help

Command Overview

pyzotero-cli is organized into several command groups:

• items: Manage library items (books, articles, etc.).
  • list, get, create, update, delete, add-tags, children, count, versions, bib, citation.
• collections: Manage collections.
  • list, get, create, update, delete, items, item-count, versions, add-item, remove-item, tags.
• tags: Manage tags.
  • list, list-for-item, delete.
• files: Manage file attachments.
  • download, upload, upload-batch.
• search: Manage saved searches.
  • list, create, delete.
• fulltext: Work with full-text content of attachments.
  • get, list-new, set.
• groups: List accessible groups.
  • list.
• util: Utility and informational commands.
  • key-info, last-modified-version, item-types, item-fields, item-type-fields, item-template.
• configure: Manage CLI configuration and profiles.
  • setup, set, get, list-profiles, current-profile.

Common Options

Many commands support common options:

• --output <format>: Set output format (json, yaml, table, keys). Default is json.
• --limit <N>: Limit the number of results.
• --start <N>: Offset for pagination.
• --sort <field>: Field to sort by (e.g., dateModified, title).
• --direction <asc|desc>: Sort direction.
• --query <term>: Quick search query.
• --qmode <titleCreatorYear|everything>: Quick search mode.
• --filter-tag <tag>: Filter by tag (can be used multiple times).
• --filter-item-type <type>: Filter by item type.
• --since <version>: Retrieve objects modified after a Zotero library version.
• --local: Use local Zotero instance (read-only mode - only GET operations will work, global option for zot).
• --profile <name>: Use a specific configuration profile (global option for zot).
• --verbose/-v, --debug: Increase verbosity.
• --no-interaction: Disable interactive prompts (e.g., for confirmations).

Examples

# Configure a profile named "personal_lib"
zot configure setup --profile personal_lib
# ... follow interactive prompts ...

# List 10 most recent journal articles in your personal library, output as a table
zot --profile personal_lib items list --filter-item-type journalArticle --sort dateModified --direction desc --limit 10 --output table

# Create a new book item from a Zotero item template
zot util item-template book > book_template.json
# ... edit book_template.json ...
zot items create --from-json book_template.json

# Get all collections containing the word "AI" in their name
zot collections list --query AI

# Download an attachment (replace <ATTACHMENT_KEY> and <PATH_TO_SAVE>)
zot files download <ATTACHMENT_KEY> -o <PATH_TO_SAVE>/attachment.pdf

# Add a tag to an item
zot items add-tags <ITEM_KEY> "needs-review" "important"

Development

Contributions are welcome!

1. Clone the repository:

   git clone https://github.com/chriscarrollsmith/pyzotero-cli.git
   cd pyzotero-cli
   

2. This project uses uv for dependency management (see uv.lock).

   # Create a venv and install dependencies
   uv sync
   

3. Run tests:

   uv run pytest
   

License

This project is licensed under the MIT License - see the LICENSE file for details (assuming one will be added).