endnote-cli

English | 中文

CLI for reading, searching, writing, and exporting EndNote .enl libraries via direct SQLite access.

Key Features

• Read -- list, get, and count references with rich table output
• Search -- quick full-text and advanced multi-field boolean search
• Write -- safely update notes, keywords, tags, ratings, labels, custom fields, translated title/author, and attachments
• Export -- BibTeX, RIS, JSON, CSV, XML, PDF copy-out, and formatted citations
• Groups & Tags -- browse group hierarchies and color-tag assignments
• Journal zone auto-tagging -- one command assigns CAS + New-Elite zone color tags using data from hitfyd/ShowJCR
• Multi-library -- manage and switch between multiple .enl files

Requirements

• Python 3.10+
• EndNote 20 or later (tested on EndNote 21)
• OS: Windows, macOS, Linux (wherever EndNote stores .enl files)
• EndNote must be closed during write operations

Installation

# Core CLI
pip install endnote-cli

# With semantic search (sentence-transformers)
pip install 'endnote-cli[semantic]'

# Everything
pip install 'endnote-cli[all]'

Quick Start

# Point to the directory containing your .enl files
endnote-cli library set-dir "C:/Users/You/Documents/EndNote"

# Set the default library
endnote-cli library set-default MyLibrary.enl

# Verify connectivity and see library stats
endnote-cli app ping
endnote-cli app info

Command Reference

Run endnote-cli <command> --help for detailed usage of any command.

Usage Examples

# Search for papers about "knowledge graph"
endnote-cli search quick "knowledge graph"

# Advanced search: title contains "RAG" AND year >= 2025
endnote-cli search advanced \
  -f title -o contains -v "RAG" \
  -f year -o gte -v "2025" --bool and

# Show group hierarchy (GroupSet -> Groups)
endnote-cli group tree

# Show all groups a reference belongs to (path format: GroupSet/Group)
endnote-cli item groups 6
endnote-cli item groups 6 --json   # machine-readable

# Export a group as BibTeX
endnote-cli export bibtex --group "RAG" -o rag_papers.bib

# Batch rename PDFs to Author_Year_Title.pdf format (dry run first)
endnote-cli write rename-pdf --all --dry-run
endnote-cli write rename-pdf --all

# Add a color tag to all arXiv papers
endnote-cli write tag 296 6

# Auto-tag every ref with its CAS zone (新锐N区 / N区25年 / 预印本)
endnote-cli write journal-tags --dry-run   # preview the plan
endnote-cli write journal-tags             # apply

# Fill the Translated Title field
endnote-cli write field 179 translated_title "肠道菌群与肺部疾病的文献计量分析"

# Write review notes back to EndNote
endnote-cli write note 296 my_review.md

# Export a group set as hierarchical XML files
endnote-cli export xml --group-set "Medical Cases"

Journal Zone Auto-Tagging

endnote-cli write journal-tags tags every reference with color-coded zone labels based on its journal. Tags applied per ref:

Matching order: ISSN first (EndNote's isbn field), then normalized journal name. Chinese-only journals and conference proceedings are skipped — they're outside the CAS scope.

# Preview — no writes
endnote-cli write journal-tags --dry-run

# Apply
endnote-cli write journal-tags

# Scope to a group
endnote-cli write journal-tags --group "RAG"

# Re-download the source data and re-tag everything
endnote-cli write journal-tags --refresh-data --refresh

Ranking data is fetched from hitfyd/ShowJCR on first use and cached under ~/.endnote-cli/jcr_cache/.

Install as a Claude Code Skill

This repo ships a Claude Code skill at .claude/skills/endnote-cli/SKILL.md. Once registered, Claude Code automatically loads it when you mention EndNote, .enl, BibTeX export, etc.

Register the skill (symlink keeps it in sync with repo updates):

# Linux / macOS
ln -s "$(pwd)/.claude/skills/endnote-cli" ~/.claude/skills/endnote-cli

# Windows (PowerShell, run as Administrator)
New-Item -ItemType SymbolicLink `
  -Path  "$HOME\.claude\skills\endnote-cli" `
  -Target "$(Get-Location)\.claude\skills\endnote-cli"

If you'd rather not symlink, just copy the folder:

cp -r .claude/skills/endnote-cli ~/.claude/skills/

Verify by running /help in Claude Code — endnote-cli should appear in the skills list.

Architecture

The Dual-Database Discovery

EndNote .enl files are SQLite 3.x databases (undocumented by Clarivate). However, EndNote maintains two copies of the database:

1. MyLibrary.enl -- the file users see
2. MyLibrary.Data/sdb/sdb.eni -- an internal mirror with the same schema

At runtime, EndNote reads from sdb.eni. All write operations must update both databases to keep them in sync. endnote-cli handles this transparently.

Key Schema Details

• Groups/GroupSets -- group definitions live in the groups table (spec column, XML blob with name + UUID); GroupSet → child group hierarchy lives in misc table code=17 (one row per GroupSet, XML blob whose <member> tags list child group UUIDs). The legacy misc code=4 (space-separated group_id set_id pairs) only contains a stale subset and should not be relied on for hierarchy
• Tags use two tables: tag_groups (XML blob with color hex) and tag_members (FTS5 virtual table with space-separated IDs)
• Multi-value fields (keywords, authors) use \r (carriage return) as the separator
• The refs table has triggers that call EN_MAKE_SORT_KEY, a custom SQLite function only available inside the EndNote application -- this means direct INSERT into refs is not safe

Safe Write Fields

The following fields can be safely updated without triggering internal triggers:

research_notes, notes, keywords, read_status, rating, label, caption, custom_1 through custom_7, translated_title, translated_author

Limitations

• No INSERT into refs -- the refs table uses triggers with a custom SQLite function (EN_MAKE_SORT_KEY) that only exists inside the EndNote runtime. Only UPDATE of safe fields is supported.
• EndNote must be closed during write operations. The application locks the database files at runtime.
• Tag colors are limited to 7 presets -- red, orange, yellow, green, blue, purple, and gray. Custom hex values render as gray in the EndNote UI.

Tested On

Other versions using .enl SQLite format may also work. Contributions and test reports welcome.

Contributing

Contributions are welcome! Please open an issue or pull request.

If you discover additional .enl schema details (new table structures, field meanings, etc.), please share -- this project is built on reverse-engineered knowledge and community contributions make it better for everyone.

License

Apache License 2.0