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
.enlfiles
Requirements
- Python 3.10+
- EndNote 20 or later (tested on EndNote 21)
- OS: Windows, macOS, Linux (wherever EndNote stores
.enlfiles) - 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:
MyLibrary.enl-- the file users seeMyLibrary.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
groupstable (speccolumn, XML blob with name + UUID); GroupSet → child group hierarchy lives inmisctablecode=17(one row per GroupSet, XML blob whose<member>tags list child group UUIDs). The legacymisc code=4(space-separatedgroup_id set_idpairs) only contains a stale subset and should not be relied on for hierarchy - Tags use two tables:
tag_groups(XML blob with color hex) andtag_members(FTS5 virtual table with space-separated IDs) - Multi-value fields (keywords, authors) use
\r(carriage return) as the separator - The
refstable has triggers that callEN_MAKE_SORT_KEY, a custom SQLite function only available inside the EndNote application -- this means directINSERTintorefsis 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
refstable uses triggers with a custom SQLite function (EN_MAKE_SORT_KEY) that only exists inside the EndNote runtime. OnlyUPDATEof 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.
