| Name | zurch JSON |
| Version |
0.7.15
JSON |
| download |
| home_page | None |
| Summary | Zurch - A CLI search tool for Zotero installations |
| upload_time | 2025-07-19 10:09:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
bibliography
cli
research
search
zotero
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# zurch - Zotero Search CLI
[](https://pypi.org/project/zurch/) [](https://github.com/kmlawson/zurch) [](https://www.zotero.org/) [](https://claude.ai/code)
A command-line interface tool to interact with your local Zotero installation and extract information from it.
## Introduction
Zotero is a powerful citation manager and research assistant for managing sources. This command-line interface (CLI) can be used to carry out read-only searches on the sqlite database of the Zotero system. Zotero developers generally do not recommend this kind of external direct access to the database. While risk of any impact on your database is low, if you have concerns, you may want to run this on a copy of your Zotero installation and use of this tool is at your own risk. Zurch will not function while the Zotero is running.
## Features
- **List Collections**: Browse all your Zotero collections and sub-collections
- **Search Items**: Find items by title or browse specific folders
- **Interactive Mode**: Select items interactively to view metadata or grab attachments
- **Attachment Management**: Copy PDF, EPUB, and text attachments to your current directory
- **Visual Indicators**: Icons show item types (π books, π articles) and attachments (π PDF/EPUB available)
- **Fast Performance**: Optimized SQLite queries for quick results
- **Cross-Platform**: Full support for Windows, macOS, and Linux with native keyboard input
- **Smart Terminal Detection**: Automatically adapts to your terminal's capabilities
- Provides READ ONLY access to your Zotero database
## Installation
### Install from PyPI
```bash
# Install with uv (recommended) - installs as a globally available tool
uv tool install zurch
# Or install with pip
pip install zurch
# Or install with pipx (if you prefer pipx over uv)
pipx install zurch
```
### Install from source
```bash
# Clone the repository
git clone https://github.com/kmlawson/zurch.git
cd zurch
# Install with uv
uv tool install .
```
## Quick Start
```bash
# List collections (up to default max items to show)
zurch -l
# List collections matching a pattern (partial matching by default)
zurch -l japan
# List collections with exact matching name
zurch -l "Japan" -k
# Browse items in a folder/s partial matching a name
zurch -f "Heritage"
# OR
zurch -f Heritage
# Search for items by name
zurch -n "People's"
zurch -n medicine
# Interactive mode is now the default - select and view metadata or grab attachments
zurch -f "Heritage"
# Interactive mode works with all searches:
zurch -n "China"
zurch -a "Smith"
# Use --nointeract to disable interactive mode and get simple list output
zurch -f "Heritage" --nointeract
zurch -n "China" --nointeract
# Show only hits with PDF/EPUB attachments
zurch -n nationalism -o
# Grabbing the PDF or EPUB attachment while in interactive mode (default):
zurch -n "Introduction to"
# Then type: 5g to grab attachment from item 5 if it includes one
# Debug mode shows additional verbose logging, including duplicates in purple
zurch -n "World History" -d
# Show IDs
zurch -n nationalism --showids
# Look up metadata of a specific item by ID
zurch --id 12345
# Grab attachment of a specific item by ID
zurch --getbyid 12345
# Disable duplicate removal to see all database entries
zurch -n "duplicate article" --no-dedupe
# Show comprehensive database statistics about the database
zurch --stats
# Show tags under item titles
zurch -n "research methods" --showtags
# Show year and author information
zurch -n "machine learning" --showyear --showauthor
# Export search results to CSV and JSON
zurch -n "digital humanities" --export csv
# Export to specific file path
zurch -n "methodology" --export json --file ~/research/methods.json
# Sort results by publication date (newest first)
zurch -n "machine learning" --sort date
# Sort by author last name
zurch -f "Papers" --sort author
# Navigate through long results with pagination
zurch -n "china" -p -x 5 # Show 5 items per page, navigate with n/p/0
# Show all results without limit
zurch -n "china" -x all # Show all results
zurch -l "Heritage" -x 0 # Show all Heritage collections
```
## Commands
### List Collections (-l/--list)
```bash
# Show all collections and sub-collections
zurch -l
# Filter collections (partial matching by default)
zurch -l "china"
# Partial match by default but use % wildcard for more control
zurch -l "china%" # starts with "china"
zurch -l "%history" # ends with "history"
# Show collection and all its sub-collections (append / to name)
zurch -l "Digital Humanities/" # Shows "Digital Humanities" and all sub-collections
zurch -l "Research/" # Shows all collections under "Research"
```
### Browse Folder (-f/--folder)
```bash
# List items in a specific folder
zurch -f "Heritage"
# Include items from folder AND all sub-collections (append / to name)
zurch -f "Digital Humanities/" # Shows items from "Digital Humanities" and all sub-collections
zurch -f "Research/" # Shows items from "Research" and all sub-collections
# Limit results
zurch -f "Digital Humanities" -x 10
# Interactive mode (default behavior)
zurch -f "Travel"
# Disable interactive mode
zurch -f "Travel" --nointeract
```
### Search by Name (-n/--name)
```bash
# Search item titles (supports AND logic for multiple words)
zurch -n machine learning # Finds items with BOTH "machine" AND "learning"
zurch -n "machine learning" # Finds items containing "machine learning"
# Case-insensitive, partial matching (default)
zurch -n "china" # Finds "China", "China's History", "Modern China", etc.
# Exact matching with -k flag
zurch -n "china" -k # Finds only items with title exactly "china"
# Handling special characters - quotes protect phrases
zurch -n "People's" Republic # AND search: items with BOTH "People's" AND "Republic"
zurch -n "People's Republic" # Phrase search: items containing exactly "People's Republic"
# Wildcard patterns (for partial matching)
zurch -n "china%" # Titles starting with "china"
zurch -n "%history" # Titles ending with "history"
zurch -n "%war%" # Titles containing "war"
```
### Search by Author (-a/--author)
```bash
# Search by author name (supports AND logic for multiple words)
zurch -a smith # Find items by authors named "smith"
zurch -a john smith # Find items with BOTH "john" AND "smith" in ANY author name
zurch -a "john smith"# Find items by authors containing "john smith"
# Exact matching with -k flag
zurch -a "john smith" -k # Find items by authors with exactly "john smith"
# Note: -fa and -la flags for first/last name search are planned for future release
# Works with first or last names
zurch -a benjamin # Finds Benjamin Franklin, Benjamin Netanyahu, etc.
```
### Filter by Tags (-t/--tag)
```bash
# Search by tag alone (case-insensitive, partial matching by default)
zurch -t methodology # Find all items tagged with "methodology"
zurch -t china japan # Find items tagged with BOTH "china" AND "japan"
zurch -t "digital humanities" # Find items tagged containing "digital humanities"
# Exact tag matching with -k flag
zurch -t "digital humanities" -k # Find items tagged with exactly "digital humanities"
# Combine with other searches for more specific results
zurch -n "machine learning" -t "data science" # Items about ML tagged with data science
zurch -f "Research" -t "to-read" # Items in Research folder tagged as to-read
zurch -a smith -t china # Items by Smith tagged with china
# Multiple tags = AND logic (item must have ALL tags)
zurch -t "important" "methodology" "python" # Items with all three tags
```
### Interactive Mode (Default Behavior)
Interactive mode is enabled by default for all searches. It allows you to:
- View detailed metadata for any item
- Navigate through multiple items
- Select an item and its attachment will be copied to current directory if you add g after the number
- Use `--nointeract` to disable interactive mode and return to simple list output
```
### Pagination (-p/--pagination)
Navigate through long result lists page by page:
```bash
# Enable pagination to browse results in manageable chunks
zurch -n "china" -p -x 5 # 5 items per page
zurch -l -p -x 10 # 10 collections per page
zurch -f "Papers" -p -x 20 # 20 folder items per page
# Navigation controls:
# n = next page
# p = previous page
# 0 or Enter = exit pagination
```
When pagination is enabled (`-p` flag), results exceeding the max limit (`-x` value) will be shown page by page with navigation prompts. This is useful for exploring large result sets without overwhelming the terminal.
### Filtering Options
- `-o/--only-attachments`: Show only items with PDF/EPUB attachments
- `--books`: Show only book items in search results
- `--articles`: Show only journal article items in search results
- `--after YEAR`: Show only items published after this year (inclusive)
- `--before YEAR`: Show only items published before this year (inclusive)
- `-t/--tag TAG [TAG...]`: Filter by tags (case-insensitive, multiple tags = AND logic)
- `-k/--exact`: Use exact matching instead of partial matching
### Database Statistics (--stats)
Get comprehensive insights into your Zotero library:
```bash
zurch --stats
```
Shows:
- **Overview**: Total items, collections, and tags
- **Item Types**: Breakdown by type (books, articles, etc.) with percentages
- **Attachments**: Count of items with/without PDF/EPUB attachments
- **Top Tags**: Most frequently used tags with item counts
- **Database Location**: Path to your Zotero database file
### Display Options
- `--showids`: Show item ID numbers in search results
- `--showtags`: Show tags for each item in search results
- `--showyear`: Show publication year for each item
- `--showauthor`: Show first author name for each item
- `--showcreated`: (Not yet implemented) Show item creation date in search results
- `--showmodified`: (Not yet implemented) Show item modification date in search results
- `--showcollections`: (Not yet implemented) Show collections each item belongs to in search results
### Sorting Options
- `--sort {t|title|d|date|a|author|c|created|m|modified}`: Sort search results by:
- `t` or `title`: Sort alphabetically by title
- `d` or `date`: Sort by publication date (auto-enables `--showyear`)
- `a` or `author`: Sort by author last name (auto-enables `--showauthor`)
- `c` or `created`: Sort by item creation date (newest first)
- `m` or `modified`: Sort by modification date (newest first)
### Export Options
- `--export [csv|json]`: Export search results to CSV or JSON format
- `--file PATH`: Specify output file path for export (defaults to current directory)
### Other Options
- `-x/--max-results N`: Limit number of results (default: 100, use 'all' or '0' for unlimited) - **Applied as final step after all filtering and deduplication**
- `-p/--pagination`: Enable pagination for long result lists (navigate with n/p/0)
- `-i/--interactive`: Enable interactive mode (default: enabled)
- `--nointeract`: Disable interactive mode and return to simple list output
- `-d/--debug`: Enable detailed logging and show purple duplicates
- `-v/--version`: Show version information
- `-h/--help`: Show help message
- `--id ID`: Show metadata for a specific item ID
- `--getbyid ID [ID...]`: Grab attachments for specific item IDs
- `--no-dedupe`: Disable automatic duplicate removal
- `--config`: Launch interactive configuration wizard
- `--stats`: Show comprehensive database statistics
### Duplicate Detection
zurch automatically removes duplicate items based on title, author, and year matching:
- **Prioritizes items with attachments** (PDF/EPUB) over those without
- **Selects most recently modified** items when attachments are equal
- **Debug mode (`-d`)** shows all duplicates in purple for investigation
- **`--no-dedupe`** flag disables deduplication to see raw database contents
Example: Search for "World History" reduces 8 duplicate items to 2 unique results.
## Configuration
### Interactive Configuration Wizard
The easiest way to configure zurch is through the interactive wizard:
```bash
zurch --config
```
This will guide you through:
- Auto-detecting your Zotero database location
- Setting interactive mode default (enabled/disabled)
- Setting default display options (IDs, tags, year, author)
- Configuring search defaults
- Setting maximum results limit
### Manual Configuration
Configuration is stored in OS-appropriate locations:
- **Windows**: `%APPDATA%\zurch\config.json`
- **macOS/Linux**: `~/.config/zurch/config.json` (or `$XDG_CONFIG_HOME/zurch/config.json`)
**Note**: If you're upgrading from an earlier version, zurch will automatically migrate your config from the old `~/.zurch-config/` location to the new standard location.
Example configuration:
```json
{
"zotero_database_path": "/path/to/Zotero/zotero.sqlite",
"max_results": 100,
"debug": false,
"interactive_mode": true,
"show_ids": false,
"show_tags": false,
"show_year": false,
"show_author": false,
"only_attachments": false
}
```
## Processing Order
Zurch processes search requests in a specific order to ensure predictable results:
1. **Search Criteria**: Find all items matching search terms (`-n`, `-a`, `-f`)
2. **Content Filters**: Apply filters like `-o` (attachments), `--books`, `--articles`, `--after`, `--before`
3. **Deduplication**: Remove duplicate items (unless `--no-dedupe` is used)
4. **Result Limiting**: Apply `-x/--max-results` limit as the final step
This means when you specify `-x 5`, you get exactly 5 items from the final processed result set. For example:
- `zurch -n "war crimes" -o -x 5` finds all "war crimes" items, filters for those with attachments, removes duplicates, then shows the first 5
- If you want 5 items before deduplication, use `--no-dedupe`
## Advanced Features
### Interactive Grab with Number Suffix
In interactive mode (default), you can append 'g' to any item number to immediately grab its attachment:
```bash
zurch -f "Papers" -i
# Output shows numbered list:
# 1. Some Paper Title π π
# 2. Another Article π π
# 3. Document Without Attachment π
# Type "2g" to grab the attachment from item 2
# Type "1" to just view metadata for item 1
```
This works for all searches by default (interactive mode is enabled by default).
### Filter by Attachments Only (-o)
Show only items that have PDF or EPUB attachments:
```bash
# Only show papers with downloadable files
zurch -f "Reading List" -o
zurch -n "machine learning" -o
# Interactive mode works with attachment filtering (default)
zurch -f "Papers" -o # Browse only items with attachments interactively
# Disable interactive mode with attachment filtering
zurch -f "Papers" -o --nointeract
```
The `-o` flag filters results to include only items with PDF or EPUB attachments, making it easy to find papers you can actually read.
## Examples
### Academic Research Workflow
```bash
# Find all collections related to your research area
zurch -l digital
# Browse a specific collection
zurch -f "Digital Humanities"
# Search for papers on a topic
zurch -n "network analysis"
# Filter by tags to find specific types of papers
zurch -n "social networks" -t "methodology"
# Interactively review papers and grab PDFs (use '3g' to grab item 3) - default behavior
zurch -n "social networks"
```
### Library Management
```bash
# Get overview of your collection structure
zurch -l
# Find items that need attention
zurch -f "To Read"
# Search for specific authors or topics
zurch -n "foucault"
# Find items by tags
zurch -t "important" -t "methodology"
# Find collections by partial name
zurch -l "digital"
```
## Safety and Compatibility
- **Read-Only Access**: zurch should never modify your Zotero database but use at your own risk
- **Database Locking**: Handles cases where Zotero is running
- **Version Compatibility**: Tested with Zotero 7.0
- **Error Handling**: Graceful handling of database issues
- **Cross-Platform**: Platform-specific path handling
- See the info/ZOTERO_DATABASE_SECURITY_REPORT.md file for an LLM generated threat assessment.
## Development
zurch is built with:
- **Python 3.8+** for broad compatibility
- **SQLite** for direct database access
- **uv** for modern Python package management
- **pytest** for comprehensive testing
### Building from Source
```bash
git clone <repository>
cd zurch
uv install
uv run pytest # Run tests
uv build # Build package
```
## Troubleshooting
### Database Not Found
If zurch can't find your Zotero database:
1. Make sure Zotero is installed and has been run at least once
2. Check the config file and set the correct path
3. Use `zurch -d` for debug information
### Database Locked
If you get a "database locked" error:
1. Close Zotero completely
2. Try the command again
3. If the issue persists, restart your computer
### No Results Found
If searches return no results:
- Check spelling and try partial terms
- Use wildcards in collection filters: `zurch -l "%term%"`
- Use `zurch -l` to see all available collections
- Collection searches use partial matching by default
## Handling Special Characters
When searching for terms containing special shell characters like apostrophes, quotes, or symbols, wrap the search term in quotes:
```bash
# Good - quoted search terms
zurch -n "China's Revolution"
zurch -f "Books & Articles"
zurch -n "Smith (2020)"
# Will cause shell errors - unquoted special chars
zurch -n China's Revolution # Shell sees unmatched quote
zurch -f Books & Articles # Shell interprets & as background process
```
**Special characters that need quoting:** `'` `"` `$` `` ` `` `\` `(` `)` `[` `]` `{` `}` `|` `&` `;` `<` `>` `*` `?`
## Unicode and International Character Support
Zurch fully supports Unicode characters in search terms, including:
```bash
# Chinese characters
zurch -n δΈε½
# Korean characters
zurch -n νκ΅
# Unicode punctuation and symbols
zurch -n "cafΓ©"
```
No special escaping is needed for Unicode characters - they work seamlessly in searches.
## Contributing
Contributions are welcome! Please read the various .md files in the repository help orient yourself.
## License
This project is licensed under the MIT License. See LICENSE file for details.
## Acknowledgments
- Thanks to the Zotero developers for such amazing software
- Built for the Zotero research community
- Inspired by the need for command-line access to Zotero data
- Uses the excellent Zotero SQLite database structure
Raw data
{
"_id": null,
"home_page": null,
"name": "zurch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bibliography, cli, research, search, zotero",
"author": null,
"author_email": "\"Konrad M. Lawson\" <kmlawson@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/79/04/85dd0928851e48216783ebc642341cdd91b35aac68b8fbd54c4a4531c816/zurch-0.7.15.tar.gz",
"platform": null,
"description": "# zurch - Zotero Search CLI\n\n[](https://pypi.org/project/zurch/) [](https://github.com/kmlawson/zurch) [](https://www.zotero.org/) [](https://claude.ai/code)\n\nA command-line interface tool to interact with your local Zotero installation and extract information from it.\n\n## Introduction\n\nZotero is a powerful citation manager and research assistant for managing sources. This command-line interface (CLI) can be used to carry out read-only searches on the sqlite database of the Zotero system. Zotero developers generally do not recommend this kind of external direct access to the database. While risk of any impact on your database is low, if you have concerns, you may want to run this on a copy of your Zotero installation and use of this tool is at your own risk. Zurch will not function while the Zotero is running.\n\n## Features\n\n- **List Collections**: Browse all your Zotero collections and sub-collections\n- **Search Items**: Find items by title or browse specific folders \n- **Interactive Mode**: Select items interactively to view metadata or grab attachments\n- **Attachment Management**: Copy PDF, EPUB, and text attachments to your current directory\n- **Visual Indicators**: Icons show item types (\ud83d\udcd7 books, \ud83d\udcc4 articles) and attachments (\ud83d\udd17 PDF/EPUB available)\n- **Fast Performance**: Optimized SQLite queries for quick results\n- **Cross-Platform**: Full support for Windows, macOS, and Linux with native keyboard input\n- **Smart Terminal Detection**: Automatically adapts to your terminal's capabilities\n- Provides READ ONLY access to your Zotero database\n\n## Installation\n\n### Install from PyPI\n\n```bash\n# Install with uv (recommended) - installs as a globally available tool\nuv tool install zurch\n\n# Or install with pip\npip install zurch\n\n# Or install with pipx (if you prefer pipx over uv)\npipx install zurch\n```\n\n### Install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/kmlawson/zurch.git\ncd zurch\n\n# Install with uv\nuv tool install .\n```\n\n## Quick Start\n\n```bash\n# List collections (up to default max items to show)\nzurch -l\n\n# List collections matching a pattern (partial matching by default)\nzurch -l japan\n\n# List collections with exact matching name\nzurch -l \"Japan\" -k\n\n# Browse items in a folder/s partial matching a name\nzurch -f \"Heritage\"\n# OR\nzurch -f Heritage\n\n# Search for items by name\nzurch -n \"People's\"\nzurch -n medicine\n\n# Interactive mode is now the default - select and view metadata or grab attachments\nzurch -f \"Heritage\"\n# Interactive mode works with all searches:\nzurch -n \"China\"\nzurch -a \"Smith\"\n\n\n# Use --nointeract to disable interactive mode and get simple list output\nzurch -f \"Heritage\" --nointeract\nzurch -n \"China\" --nointeract\n\n# Show only hits with PDF/EPUB attachments\nzurch -n nationalism -o\n\n# Grabbing the PDF or EPUB attachment while in interactive mode (default):\nzurch -n \"Introduction to\"\n# Then type: 5g to grab attachment from item 5 if it includes one\n\n# Debug mode shows additional verbose logging, including duplicates in purple\nzurch -n \"World History\" -d\n\n# Show IDs \nzurch -n nationalism --showids\n\n# Look up metadata of a specific item by ID\nzurch --id 12345\n\n# Grab attachment of a specific item by ID\nzurch --getbyid 12345\n\n# Disable duplicate removal to see all database entries\nzurch -n \"duplicate article\" --no-dedupe\n\n# Show comprehensive database statistics about the database\nzurch --stats\n\n# Show tags under item titles\nzurch -n \"research methods\" --showtags\n\n# Show year and author information\nzurch -n \"machine learning\" --showyear --showauthor\n\n# Export search results to CSV and JSON\nzurch -n \"digital humanities\" --export csv\n\n# Export to specific file path\nzurch -n \"methodology\" --export json --file ~/research/methods.json\n\n# Sort results by publication date (newest first)\nzurch -n \"machine learning\" --sort date\n\n# Sort by author last name\nzurch -f \"Papers\" --sort author\n\n# Navigate through long results with pagination\nzurch -n \"china\" -p -x 5 # Show 5 items per page, navigate with n/p/0\n\n# Show all results without limit\nzurch -n \"china\" -x all # Show all results\nzurch -l \"Heritage\" -x 0 # Show all Heritage collections\n```\n\n## Commands\n\n### List Collections (-l/--list)\n```bash\n# Show all collections and sub-collections\nzurch -l\n\n# Filter collections (partial matching by default)\nzurch -l \"china\"\n\n# Partial match by default but use % wildcard for more control\nzurch -l \"china%\" # starts with \"china\" \nzurch -l \"%history\" # ends with \"history\"\n\n# Show collection and all its sub-collections (append / to name)\nzurch -l \"Digital Humanities/\" # Shows \"Digital Humanities\" and all sub-collections\nzurch -l \"Research/\" # Shows all collections under \"Research\"\n```\n\n### Browse Folder (-f/--folder)\n```bash\n# List items in a specific folder\nzurch -f \"Heritage\"\n\n# Include items from folder AND all sub-collections (append / to name)\nzurch -f \"Digital Humanities/\" # Shows items from \"Digital Humanities\" and all sub-collections\nzurch -f \"Research/\" # Shows items from \"Research\" and all sub-collections\n\n# Limit results\nzurch -f \"Digital Humanities\" -x 10\n\n# Interactive mode (default behavior)\nzurch -f \"Travel\"\n\n# Disable interactive mode\nzurch -f \"Travel\" --nointeract\n```\n\n### Search by Name (-n/--name)\n```bash\n# Search item titles (supports AND logic for multiple words)\nzurch -n machine learning # Finds items with BOTH \"machine\" AND \"learning\"\nzurch -n \"machine learning\" # Finds items containing \"machine learning\"\n\n# Case-insensitive, partial matching (default)\nzurch -n \"china\" # Finds \"China\", \"China's History\", \"Modern China\", etc.\n\n# Exact matching with -k flag\nzurch -n \"china\" -k # Finds only items with title exactly \"china\"\n\n# Handling special characters - quotes protect phrases\nzurch -n \"People's\" Republic # AND search: items with BOTH \"People's\" AND \"Republic\"\nzurch -n \"People's Republic\" # Phrase search: items containing exactly \"People's Republic\"\n\n# Wildcard patterns (for partial matching)\nzurch -n \"china%\" # Titles starting with \"china\"\nzurch -n \"%history\" # Titles ending with \"history\" \nzurch -n \"%war%\" # Titles containing \"war\"\n```\n\n### Search by Author (-a/--author)\n```bash\n# Search by author name (supports AND logic for multiple words)\nzurch -a smith # Find items by authors named \"smith\"\nzurch -a john smith # Find items with BOTH \"john\" AND \"smith\" in ANY author name\nzurch -a \"john smith\"# Find items by authors containing \"john smith\"\n\n# Exact matching with -k flag\nzurch -a \"john smith\" -k # Find items by authors with exactly \"john smith\"\n\n# Note: -fa and -la flags for first/last name search are planned for future release\n\n# Works with first or last names\nzurch -a benjamin # Finds Benjamin Franklin, Benjamin Netanyahu, etc.\n```\n\n### Filter by Tags (-t/--tag)\n```bash\n# Search by tag alone (case-insensitive, partial matching by default)\nzurch -t methodology # Find all items tagged with \"methodology\"\nzurch -t china japan # Find items tagged with BOTH \"china\" AND \"japan\"\nzurch -t \"digital humanities\" # Find items tagged containing \"digital humanities\"\n\n# Exact tag matching with -k flag\nzurch -t \"digital humanities\" -k # Find items tagged with exactly \"digital humanities\"\n\n# Combine with other searches for more specific results\nzurch -n \"machine learning\" -t \"data science\" # Items about ML tagged with data science\nzurch -f \"Research\" -t \"to-read\" # Items in Research folder tagged as to-read\nzurch -a smith -t china # Items by Smith tagged with china\n\n# Multiple tags = AND logic (item must have ALL tags)\nzurch -t \"important\" \"methodology\" \"python\" # Items with all three tags\n```\n\n### Interactive Mode (Default Behavior)\nInteractive mode is enabled by default for all searches. It allows you to:\n- View detailed metadata for any item\n- Navigate through multiple items\n- Select an item and its attachment will be copied to current directory if you add g after the number\n- Use `--nointeract` to disable interactive mode and return to simple list output\n```\n\n### Pagination (-p/--pagination)\nNavigate through long result lists page by page:\n```bash\n# Enable pagination to browse results in manageable chunks\nzurch -n \"china\" -p -x 5 # 5 items per page\nzurch -l -p -x 10 # 10 collections per page\nzurch -f \"Papers\" -p -x 20 # 20 folder items per page\n\n# Navigation controls:\n# n = next page\n# p = previous page \n# 0 or Enter = exit pagination\n```\n\nWhen pagination is enabled (`-p` flag), results exceeding the max limit (`-x` value) will be shown page by page with navigation prompts. This is useful for exploring large result sets without overwhelming the terminal.\n\n### Filtering Options\n- `-o/--only-attachments`: Show only items with PDF/EPUB attachments\n- `--books`: Show only book items in search results \n- `--articles`: Show only journal article items in search results\n- `--after YEAR`: Show only items published after this year (inclusive)\n- `--before YEAR`: Show only items published before this year (inclusive)\n- `-t/--tag TAG [TAG...]`: Filter by tags (case-insensitive, multiple tags = AND logic)\n- `-k/--exact`: Use exact matching instead of partial matching\n\n### Database Statistics (--stats)\nGet comprehensive insights into your Zotero library:\n```bash\nzurch --stats\n```\nShows:\n- **Overview**: Total items, collections, and tags\n- **Item Types**: Breakdown by type (books, articles, etc.) with percentages\n- **Attachments**: Count of items with/without PDF/EPUB attachments\n- **Top Tags**: Most frequently used tags with item counts\n- **Database Location**: Path to your Zotero database file\n\n### Display Options\n- `--showids`: Show item ID numbers in search results\n- `--showtags`: Show tags for each item in search results\n- `--showyear`: Show publication year for each item\n- `--showauthor`: Show first author name for each item\n- `--showcreated`: (Not yet implemented) Show item creation date in search results\n- `--showmodified`: (Not yet implemented) Show item modification date in search results\n- `--showcollections`: (Not yet implemented) Show collections each item belongs to in search results\n\n### Sorting Options\n- `--sort {t|title|d|date|a|author|c|created|m|modified}`: Sort search results by:\n - `t` or `title`: Sort alphabetically by title\n - `d` or `date`: Sort by publication date (auto-enables `--showyear`)\n - `a` or `author`: Sort by author last name (auto-enables `--showauthor`)\n - `c` or `created`: Sort by item creation date (newest first)\n - `m` or `modified`: Sort by modification date (newest first)\n\n### Export Options\n- `--export [csv|json]`: Export search results to CSV or JSON format\n- `--file PATH`: Specify output file path for export (defaults to current directory)\n\n### Other Options\n- `-x/--max-results N`: Limit number of results (default: 100, use 'all' or '0' for unlimited) - **Applied as final step after all filtering and deduplication**\n- `-p/--pagination`: Enable pagination for long result lists (navigate with n/p/0)\n- `-i/--interactive`: Enable interactive mode (default: enabled)\n- `--nointeract`: Disable interactive mode and return to simple list output\n- `-d/--debug`: Enable detailed logging and show purple duplicates\n- `-v/--version`: Show version information\n- `-h/--help`: Show help message\n- `--id ID`: Show metadata for a specific item ID\n- `--getbyid ID [ID...]`: Grab attachments for specific item IDs\n- `--no-dedupe`: Disable automatic duplicate removal\n- `--config`: Launch interactive configuration wizard\n- `--stats`: Show comprehensive database statistics\n\n### Duplicate Detection\nzurch automatically removes duplicate items based on title, author, and year matching:\n- **Prioritizes items with attachments** (PDF/EPUB) over those without\n- **Selects most recently modified** items when attachments are equal\n- **Debug mode (`-d`)** shows all duplicates in purple for investigation\n- **`--no-dedupe`** flag disables deduplication to see raw database contents\n\nExample: Search for \"World History\" reduces 8 duplicate items to 2 unique results.\n\n## Configuration\n\n### Interactive Configuration Wizard\nThe easiest way to configure zurch is through the interactive wizard:\n```bash\nzurch --config\n```\n\nThis will guide you through:\n- Auto-detecting your Zotero database location\n- Setting interactive mode default (enabled/disabled)\n- Setting default display options (IDs, tags, year, author)\n- Configuring search defaults\n- Setting maximum results limit\n\n### Manual Configuration\nConfiguration is stored in OS-appropriate locations:\n- **Windows**: `%APPDATA%\\zurch\\config.json`\n- **macOS/Linux**: `~/.config/zurch/config.json` (or `$XDG_CONFIG_HOME/zurch/config.json`)\n\n**Note**: If you're upgrading from an earlier version, zurch will automatically migrate your config from the old `~/.zurch-config/` location to the new standard location.\n\nExample configuration:\n```json\n{\n \"zotero_database_path\": \"/path/to/Zotero/zotero.sqlite\",\n \"max_results\": 100,\n \"debug\": false,\n \"interactive_mode\": true,\n \"show_ids\": false,\n \"show_tags\": false,\n \"show_year\": false,\n \"show_author\": false,\n \"only_attachments\": false\n}\n```\n\n## Processing Order\n\nZurch processes search requests in a specific order to ensure predictable results:\n\n1. **Search Criteria**: Find all items matching search terms (`-n`, `-a`, `-f`)\n2. **Content Filters**: Apply filters like `-o` (attachments), `--books`, `--articles`, `--after`, `--before`\n3. **Deduplication**: Remove duplicate items (unless `--no-dedupe` is used)\n4. **Result Limiting**: Apply `-x/--max-results` limit as the final step\n\nThis means when you specify `-x 5`, you get exactly 5 items from the final processed result set. For example:\n- `zurch -n \"war crimes\" -o -x 5` finds all \"war crimes\" items, filters for those with attachments, removes duplicates, then shows the first 5\n- If you want 5 items before deduplication, use `--no-dedupe`\n\n## Advanced Features\n\n### Interactive Grab with Number Suffix\nIn interactive mode (default), you can append 'g' to any item number to immediately grab its attachment:\n\n```bash\nzurch -f \"Papers\" -i\n# Output shows numbered list:\n# 1. Some Paper Title \ud83d\udcd5 \ud83d\udd17\n# 2. Another Article \ud83d\udcc4 \ud83d\udd17 \n# 3. Document Without Attachment \ud83d\udcc4\n\n# Type \"2g\" to grab the attachment from item 2\n# Type \"1\" to just view metadata for item 1\n```\n\nThis works for all searches by default (interactive mode is enabled by default).\n\n### Filter by Attachments Only (-o)\nShow only items that have PDF or EPUB attachments:\n\n```bash\n# Only show papers with downloadable files\nzurch -f \"Reading List\" -o\nzurch -n \"machine learning\" -o\n\n# Interactive mode works with attachment filtering (default)\nzurch -f \"Papers\" -o # Browse only items with attachments interactively\n\n# Disable interactive mode with attachment filtering\nzurch -f \"Papers\" -o --nointeract\n```\n\nThe `-o` flag filters results to include only items with PDF or EPUB attachments, making it easy to find papers you can actually read.\n\n## Examples\n\n### Academic Research Workflow\n```bash\n# Find all collections related to your research area\nzurch -l digital\n\n# Browse a specific collection\nzurch -f \"Digital Humanities\"\n\n# Search for papers on a topic\nzurch -n \"network analysis\"\n\n# Filter by tags to find specific types of papers\nzurch -n \"social networks\" -t \"methodology\"\n\n# Interactively review papers and grab PDFs (use '3g' to grab item 3) - default behavior\nzurch -n \"social networks\"\n```\n\n### Library Management\n```bash\n# Get overview of your collection structure\nzurch -l\n\n# Find items that need attention \nzurch -f \"To Read\"\n\n# Search for specific authors or topics\nzurch -n \"foucault\"\n\n# Find items by tags\nzurch -t \"important\" -t \"methodology\"\n\n# Find collections by partial name\nzurch -l \"digital\"\n```\n\n## Safety and Compatibility\n\n- **Read-Only Access**: zurch should never modify your Zotero database but use at your own risk\n- **Database Locking**: Handles cases where Zotero is running\n- **Version Compatibility**: Tested with Zotero 7.0\n- **Error Handling**: Graceful handling of database issues\n- **Cross-Platform**: Platform-specific path handling\n- See the info/ZOTERO_DATABASE_SECURITY_REPORT.md file for an LLM generated threat assessment. \n\n## Development\n\nzurch is built with:\n- **Python 3.8+** for broad compatibility\n- **SQLite** for direct database access\n- **uv** for modern Python package management\n- **pytest** for comprehensive testing\n\n### Building from Source\n```bash\ngit clone <repository>\ncd zurch\nuv install\nuv run pytest # Run tests\nuv build # Build package\n```\n\n## Troubleshooting\n\n### Database Not Found\nIf zurch can't find your Zotero database:\n1. Make sure Zotero is installed and has been run at least once\n2. Check the config file and set the correct path\n3. Use `zurch -d` for debug information\n\n### Database Locked\nIf you get a \"database locked\" error:\n1. Close Zotero completely\n2. Try the command again\n3. If the issue persists, restart your computer\n\n### No Results Found\nIf searches return no results:\n- Check spelling and try partial terms\n- Use wildcards in collection filters: `zurch -l \"%term%\"`\n- Use `zurch -l` to see all available collections\n- Collection searches use partial matching by default\n\n## Handling Special Characters\n\nWhen searching for terms containing special shell characters like apostrophes, quotes, or symbols, wrap the search term in quotes:\n\n```bash\n# Good - quoted search terms\nzurch -n \"China's Revolution\"\nzurch -f \"Books & Articles\" \nzurch -n \"Smith (2020)\"\n\n# Will cause shell errors - unquoted special chars\nzurch -n China's Revolution # Shell sees unmatched quote\nzurch -f Books & Articles # Shell interprets & as background process\n```\n\n**Special characters that need quoting:** `'` `\"` `$` `` ` `` `\\` `(` `)` `[` `]` `{` `}` `|` `&` `;` `<` `>` `*` `?`\n\n## Unicode and International Character Support\n\nZurch fully supports Unicode characters in search terms, including:\n\n```bash\n# Chinese characters\nzurch -n \u4e2d\u56fd\n\n# Korean characters\nzurch -n \ud55c\uad6d\n\n# Unicode punctuation and symbols\nzurch -n \"caf\u00e9\"\n```\n\nNo special escaping is needed for Unicode characters - they work seamlessly in searches.\n\n## Contributing\n\nContributions are welcome! Please read the various .md files in the repository help orient yourself. \n\n## License\n\nThis project is licensed under the MIT License. See LICENSE file for details.\n\n## Acknowledgments\n\n- Thanks to the Zotero developers for such amazing software\n- Built for the Zotero research community\n- Inspired by the need for command-line access to Zotero data\n- Uses the excellent Zotero SQLite database structure\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Zurch - A CLI search tool for Zotero installations",
"version": "0.7.15",
"project_urls": {
"Homepage": "https://github.com/kmlawson/zurch",
"Issues": "https://github.com/kmlawson/zurch/issues",
"Repository": "https://github.com/kmlawson/zurch.git"
},
"split_keywords": [
"bibliography",
" cli",
" research",
" search",
" zotero"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dd381488d101de8fb3d30dc976eed555c3d653feb33532b80ca3fce629bde999",
"md5": "7a6637d80ad3e780e6aaf8ca226ee1b3",
"sha256": "e1460b0ef85e569a2bcd9ae8a3b4a3d325882160a973dcd8ab99ae81947025ec"
},
"downloads": -1,
"filename": "zurch-0.7.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a6637d80ad3e780e6aaf8ca226ee1b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 97542,
"upload_time": "2025-07-19T10:09:42",
"upload_time_iso_8601": "2025-07-19T10:09:42.374731Z",
"url": "https://files.pythonhosted.org/packages/dd/38/1488d101de8fb3d30dc976eed555c3d653feb33532b80ca3fce629bde999/zurch-0.7.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "790485dd0928851e48216783ebc642341cdd91b35aac68b8fbd54c4a4531c816",
"md5": "f6f1688cd3c0a58adb25f818c8b1fb83",
"sha256": "39d4ab43117e1e8469f1b7b8a98969395b41b2f3914e12fcbcc73f5bf2ffebeb"
},
"downloads": -1,
"filename": "zurch-0.7.15.tar.gz",
"has_sig": false,
"md5_digest": "f6f1688cd3c0a58adb25f818c8b1fb83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 223220,
"upload_time": "2025-07-19T10:09:44",
"upload_time_iso_8601": "2025-07-19T10:09:44.774876Z",
"url": "https://files.pythonhosted.org/packages/79/04/85dd0928851e48216783ebc642341cdd91b35aac68b8fbd54c4a4531c816/zurch-0.7.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 10:09:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kmlawson",
"github_project": "zurch",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "zurch"
}
