pyzotero-cli 0.1.0__tar.gz

pyzotero_cli-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: pyzotero-cli
+Version: 0.1.0
+Summary: A CLI wrapper for pyzotero
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.2.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pyzotero>=1.6.11
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: pytest>=7.0
+Requires-Dist: python-dotenv>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+
+# pyzotero-cli
+
+[![PyPI version](https://badge.fury.io/py/pyzotero-cli.svg)](https://badge.fury.io/py/pyzotero-cli)
+![Python Version](https://img.shields.io/pypi/pyversions/pyzotero-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<!-- [![Build Status](https://github.com/chriscarrollsmith/pyzotero-cli/actions/workflows/python-package.yml/badge.svg)](https://github.com/chriscarrollsmith/pyzotero-cli/actions/workflows/python-package.yml) -->
+
+`pyzotero-cli` is a powerful command-line interface (CLI) for interacting with your Zotero library. It acts as a wrapper around the excellent [pyzotero](https://github.com/zotero/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.
+
+```bash
+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:
+
+```bash
+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](https://www.zotero.org/settings/keys)).
+*   **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:
+
+```bash
+# 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.
+
+```bash
+# 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
+
+```bash
+# 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:
+    ```bash
+    git clone https://github.com/chriscarrollsmith/pyzotero-cli.git
+    cd pyzotero-cli
+    ```
+
+2.  This project uses `uv` for dependency management (see `uv.lock`).
+    ```bash
+    # Create a venv and install dependencies
+    uv sync
+    ```
+
+3.  Run tests:
+    ```bash
+    uv run pytest
+    ```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details (assuming one will be added).

pyzotero_cli-0.1.0/README.md

@@ -0,0 +1,199 @@
+# pyzotero-cli
+
+[![PyPI version](https://badge.fury.io/py/pyzotero-cli.svg)](https://badge.fury.io/py/pyzotero-cli)
+![Python Version](https://img.shields.io/pypi/pyversions/pyzotero-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<!-- [![Build Status](https://github.com/chriscarrollsmith/pyzotero-cli/actions/workflows/python-package.yml/badge.svg)](https://github.com/chriscarrollsmith/pyzotero-cli/actions/workflows/python-package.yml) -->
+
+`pyzotero-cli` is a powerful command-line interface (CLI) for interacting with your Zotero library. It acts as a wrapper around the excellent [pyzotero](https://github.com/zotero/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.
+
+```bash
+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:
+
+```bash
+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](https://www.zotero.org/settings/keys)).
+*   **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:
+
+```bash
+# 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.
+
+```bash
+# 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
+
+```bash
+# 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:
+    ```bash
+    git clone https://github.com/chriscarrollsmith/pyzotero-cli.git
+    cd pyzotero-cli
+    ```
+
+2.  This project uses `uv` for dependency management (see `uv.lock`).
+    ```bash
+    # Create a venv and install dependencies
+    uv sync
+    ```
+
+3.  Run tests:
+    ```bash
+    uv run pytest
+    ```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details (assuming one will be added).

pyzotero_cli-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "pyzotero-cli"
+version = "0.1.0"
+description = "A CLI wrapper for pyzotero"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.2.0",
+    "pyyaml>=6.0.2",
+    "pyzotero>=1.6.11",
+    "tabulate>=0.9.0",
+    "pytest>=7.0",
+    "python-dotenv>=1.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.5",
+]
+
+[project.scripts]
+zot = "pyzotero_cli.zot_cli:zot"
+
+[tool.setuptools.packages.find]
+include = ["pyzotero_cli"]
+
+[tool.uv]
+package = true

pyzotero_cli-0.1.0/pyzotero_cli/__init__.py

@@ -0,0 +1 @@
+