pyzotero-cli 0.1.1

A CLI wrapper for pyzotero

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.

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.

pip install pyzotero-cli

Configuration

Before you can use pyzotero-cli to interact with your Zotero library (unless using the --local flag for a local 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).
• 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, 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).