zotero-lib

A powerful TypeScript library and CLI tool for interacting with the Zotero API. Part of the OpenDevEd zotzen ecosystem for managing academic libraries.

Table of Contents

• Installation
• Quick Start
• CLI Commands
• Library Usage
• Configuration
• Development
• API Reference
• Contributing
• License

Installation

As a CLI Tool (Global)

npm install -g zotero-lib
# or
yarn global add zotero-lib

As a Library (Local)

npm install zotero-lib
# or
yarn add zotero-lib

From Source

git clone https://github.com/OpenDevEd/zotero-lib.git
cd zotero-lib
npm install
npm run build

Quick Start

CLI Basics

# Show help
zotero-lib -h
zotero-lib --help

# Show version
zotero-lib -v

# Get items from a group
zotero-lib items --group-id 12345 --api-key YOUR_API_KEY --filter '{"limit": 10}'

# Create an item
zotero-lib create --group-id 12345 --api-key YOUR_API_KEY --items '{"title": "My Book", "itemType": "book"}'

Environment Variables

Set these for convenience (avoids passing --api-key every time):

export ZOTERO_API_KEY="your-api-key-here"
export ZOTERO_GROUP_ID="12345"

Or create a .env file:

ZOTERO_API_KEY=your-api-key-here
ZOTERO_GROUP_ID=12345

CLI Commands

Item Management

Create Items

# From file containing JSON
zotero-lib create --files items.json

# From command line JSON
zotero-lib create --items '{"title": "Book Title", "itemType": "book"}'

# Multiple items
zotero-lib create --items '{"title": "Book 1"}' '{"title": "Book 2"}'

Update Items

# Update by key
zotero-lib update --key ABC123 --json '{"title": "Updated Title"}'

# Replace entire item
zotero-lib update --replace --key ABC123 --json '{"title": "New Item", "itemType": "book"}'

# From file
zotero-lib update --key ABC123 --file items.json

Get Items

# Single item
zotero-lib item --key ABC123

# Multiple items with filters
zotero-lib items --filter '{"limit": 50, "start": 0}'

# Top-level items only (no attachments/notes)
zotero-lib items --top

# Items in specific collection
zotero-lib items --collection ABC123

Delete Items

# Move to trash
zotero-lib delete --key ABC123

# Permanent delete
zotero-lib delete --key ABC123 --permanent

Collection Management

# List collections
zotero-lib collections --group-id 12345

# Create collection
zotero-lib collection --group-id 12345 --name "My Collection"

# Update collection
zotero-lib update-collection --key ABC123 --name "New Name"

# Delete collection
zotero-lib delete-collection --key ABC123

Tag Management

# List tags
zotero-lib tags --group-id 12345

# Get items by tag
zotero-lib items --tag "important"

Attachments

# Add attachment
zotero-lib attachment --key ABC123 --addfiles file.pdf

# Attach link
zotero-lib attach-link --key ABC123 --url "https://example.com"

# Attach note
zotero-lib attach-note --key ABC123 --note "This is a note"

DOI Operations

# Get DOI for an item
zotero-lib get-doi --key ABC123

# Update DOI
zotero-lib update-doi --key ABC123 --doi "10.1234/example"

Field Operations

# Get field value
zotero-lib field --key ABC123 --field title

# Set field value
zotero-lib field --key ABC123 --field title --value "New Title"

# Get extra field
zotero-lib field --key ABC123 --extra --field customField

Database Sync

Sync your Zotero library locally using SQLite:

# Initial sync
zotero-lib db backup.db --sync --group-id 12345

# Incremental sync (only fetches changes since last sync)
zotero-lib db backup.db --sync

# Export to JSON
zotero-lib db backup.db --export-json=backup.json

# Lookup items locally
zotero-lib db backup.db --lookup --keys ABC123,DEF456

# Scheduled sync (daemon mode)
zotero-lib db backup.db --sync --daemon="0 * * * *"  # Every hour

# Find inconsistent items
zotero-lib db backup.db --errors

Merge & Deduplicate

Intelligent Merge (Recommended)

# Merge duplicates with intelligent strategy
zotero-lib merge --group-id 12345 --data duplicates.json --strategy intelligent_fill

# Available strategies:
#   - intelligent_fill (default): Fill empty fields from duplicates
#   - keep_oldest: Preserve oldest item
#   - keep_newest: Preserve newest item

Deduplicate

# Find duplicates
zotero-lib deduplicate --group-id 12345 --options identical

# With output file
zotero-lib deduplicate --group-id 12345 --output duplicates.json

Other Commands

# Get item types
zotero-lib types --group-id 12345

# List groups
zotero-lib groups

# Search items
zotero-lib searches --group-id 12345

# Get library fields
zotero-lib fields --group-id 12345

# Create bibliography
zotero-lib bibliography --group-id 12345 --style apa

# Get item template
zotero-lib TEMPLATE --item-type book

Library Usage

Import the Library

import { Zotero } from 'zotero-lib';

Initialize

const zotero = new Zotero({
  apiKey: 'your-api-key',
  groupId: 12345
});

Fetch Items

// Get all items
const items = await zotero.getItems();

// Get items with filters
const items = await zotero.getItems({
  limit: 50,
  start: 0,
  collection: 'collection-key',
  tag: 'important'
});

// Get single item
const item = await zotero.getItem('ABC123');

Create Items

const newItem = await zotero.createItem({
  title: 'My Book',
  itemType: 'book',
  creators: [{
    creatorType: 'author',
    firstName: 'John',
    lastName: 'Doe'
  }]
});

Update Items

await zotero.updateItem('ABC123', {
  title: 'Updated Title'
});

Merge Items

import { merge_items, MergeStrategy } from 'zotero-lib/build/utils/merge';

const result = await merge_items(
  groupId,
  itemKeys,
  MergeStrategy.INTELLIGENT_FILL
);

console.log(result);

Configuration

Config File

Create zotero.config.json in your project root:

{
  "apiKey": "your-api-key",
  "groupId": 12345,
  "libraryType": "group"
}

Environment Variables

Variable	Description
ZOTERO_API_KEY	Your Zotero API key
ZOTERO_GROUP_ID	Default group ID
ZOTERO_LIBRARY_TYPE	'user' or 'group' (default: 'user')

Development

Setup

npm install
npm run build

Available Scripts

# Development
npm run dev          # Run with ts-node

# Build
npm run build        # Build for production

# Test
npm test             # Run Jest tests
npm run legacy:test  # Run legacy tests

# Lint
npx eslint src/

# Type checking
npx tsc --noEmit

# Generate docs
npm run docs         # Generate TypeScript documentation

# Publish
npm run publish:patch  # Patch release
npm run publish:minor  # Minor release
npm run publish:major  # Major release

Running Tests

# All tests
npm test

# Specific test file
npx jest tests/utils.test.ts

# With coverage
npm test -- --coverage

API Reference

Zotero Class

Constructor

new Zotero(config: ZoteroConfig)

Methods

Method	Description
getItems(options?)	Fetch items from library
getItem(key)	Fetch single item
createItem(item)	Create new item
updateItem(key, data)	Update item
deleteItem(key)	Delete item
getCollections()	List collections
createCollection(name, parent?)	Create collection
getTags()	List tags
getItemTypes()	List item types
getFields()	List available fields

Merge Strategies

enum MergeStrategy {
  INTELLIGENT_FILL = 'intelligent_fill',
  KEEP_OLDEST = 'keep_oldest',
  KEEP_NEWEST = 'keep_newest'
}

Related Projects

This library is part of the OpenDevEd zotzen ecosystem:

• zenodo-lib - Zenodo API library
• zotzen-lib - Combined Zotero + Zenodo
• zotzen-web - Web interface

License

ISC License - see LICENSE file for details.

Credits

Originally built on zotero-cli by @bjohas, @retorquere, and @a1diablo.

---

For more details, see the full documentation or run zotero-lib --help.