██████╗ █████╗ ██████╗ ███████╗██████╗ ██████╗██╗ ██╗
 ██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝██║ ██║
 ██████╔╝███████║██████╔╝█████╗ ██████╔╝██║ ██║ ██║
 ██╔═══╝ ██╔══██║██╔═══╝ ██╔══╝ ██╔══██╗██║ ██║ ██║
 ██║ ██║ ██║██║ ███████╗██║ ██║╚██████╗███████╗██║
 ╚═╝ ╚═╝ ╚═╝╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝
 
 📚 Your Command-Line Research Paper Manager 📚

A powerful command-line paper management system for researchers and academics. PaperCLI helps you organize, search, and manage your research papers with an intuitive terminal interface.

• Multiple Import Sources: Add papers from arXiv, DBLP, OpenReview, local PDFs, BibTeX, and RIS files
• Smart Metadata Extraction: Automatically extract metadata from PDFs and online sources
• Collection Organization: Organize papers into custom collections
• Comprehensive Search: Filter papers by title, author, venue, year, type, and collection

• Interactive Chat Interface: Local chat dialog with configurable OpenAI models (GPT-4o, etc.)
  • Automatic PDF content inclusion (configurable pages limit) for comprehensive context
  • Auto-summarization for papers without notes
  • Input history navigation and keyboard shortcuts
• Browser Chat Integration: Quick access to Claude, ChatGPT, or Gemini web interfaces
• Enhanced Metadata: AI-powered metadata extraction and improvement

• Multiple Export Formats: Export to BibTeX, IEEE references, Markdown, HTML, and JSON
• Clipboard Support: Copy paper data directly to clipboard
• PDF Management: Automatic PDF downloading and organization

• OneDrive Sync: Comprehensive synchronization with UUID-based paper matching
  • Conflict detection and resolution options
  • Edit paper titles without creating duplicates
  • Automatic schema migration and UUID synchronization
• Database Health: Built-in diagnostic tools for database maintenance
• Interactive UI: Modern terminal interface with auto-completion and consistent status messaging
• Multi-selection: Batch operations on multiple papers
• Real-time Search: Filter and search as you type
• Version Management: Automatic update checking and seamless upgrades
• Cross-platform: Works with pipx, pip, or source installations

• Python 3.8 or higher
• pip package manager

# Install directly from GitHub
pipx install git+https://github.com/SXKDZ/papercli.git
# Run from anywhere
papercli

# Install directly from GitHub
pip install git+https://github.com/SXKDZ/papercli.git
# Run from anywhere
papercli

git clone https://github.com/SXKDZ/papercli.git
cd papercli
pip install -r requirements.txt
# Run the application
python -m ng.papercli

1. Launch PaperCLI:

   # If installed via pipx or pip
   papercli
   # Or if running from source
   python -m ng.papercli

2. Set up OpenAI API key (prompted on first run if missing):

   • Option 1: Environment variable (recommended)

     export OPENAI_API_KEY=your_openai_api_key_here

   • Option 2: Create .env file in current directory or ~/.papercli/

     echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

3. Add your first paper (arXiv is now the default option):

   /add arxiv 2307.10635
   

4. Search and filter:

   /filter all machine learning
   

5. Export your library:

   /export bibtex
   

• /add - Open add dialog or add paper directly
  • /add arxiv <id> - Add from an arXiv ID (e.g., 2307.10635)
  • /add dblp <url> - Add from a DBLP URL
  • /add openreview <id> - Add from an OpenReview ID
  • /add doi <id> - Add from a DOI
  • /add pdf <path> - Add from a local PDF file
  • /add bib <path> - Add papers from a BibTeX file
  • /add ris <path> - Add papers from a RIS file
  • /add manual - Add a paper with manual entry
• /filter - Filter papers by criteria or search all fields
  • /filter all <keyword> - Search across all fields
  • /filter title <keyword> - Search in paper titles
  • /filter abstract <keyword> - Search in paper abstracts
  • /filter notes <keyword> - Search in paper notes
  • /filter year <year> - Filter by publication year
  • /filter author <name> - Filter by author name
  • /filter venue <name> - Filter by venue name
  • /filter type <type> - Filter by paper type
  • /filter collection <name> - Filter by collection name
• /sort - Open sort dialog or sort directly
  • /sort title - Sort by title
  • /sort authors - Sort by author names
  • /sort venue - Sort by venue
  • /sort year - Sort by publication year
• /all - Show all papers in the database
• /select - Enter multi-selection mode to act on multiple papers
• /clear - Clear all selected papers
• /help - Show help panel (or press F1)
• /log - Show the error log panel
• /exit - Exit the application (or press Ctrl+C)

Work on the paper under the cursor ► or selected papers ✓:

• /chat [provider] - Chat with an LLM about the paper(s)
  • /chat - Open local chat interface with OpenAI GPT (interactive dialog)
  • /chat claude - Open Claude AI in browser
  • /chat chatgpt - Open ChatGPT in browser
  • /chat gemini - Open Google Gemini in browser
• /edit - Open edit dialog or edit field directly
  • /edit extract-pdf - Extract metadata from PDF
  • /edit summarize - Generate LLM summary
  • /edit title <text> - Edit the title
  • /edit abstract <text> - Edit the abstract
  • /edit notes <text> - Edit personal notes
  • /edit venue_full <text> - Edit full venue name
  • /edit venue_acronym <text> - Edit venue acronym
  • /edit year <number> - Edit publication year
  • /edit paper_type <type> - Edit paper type
  • /edit doi <text> - Edit DOI
  • /edit pages <text> - Edit page numbers
  • /edit preprint_id <text> - Edit preprint ID
  • /edit url <text> - Edit paper URL
• /open - Open the PDF for the paper(s)
• /detail - Show detailed metadata for the paper(s)
• /export - Export paper(s) to a file or clipboard
  • /export bibtex - Export to BibTeX format
  • /export ieee - Export to IEEE reference format
  • /export markdown - Export to Markdown format
  • /export html - Export to HTML format
  • /export json - Export to JSON format
• /copy-prompt - Copy paper prompt to clipboard for use with any LLM
• /delete - Delete the paper(s) from the library

• /collect - Manage collections
• /collect purge - Delete all empty collections
• /add-to - Add selected paper(s) to a collection
• /remove-from - Remove selected paper(s) from a collection

• /sync - OneDrive synchronization with conflict detection and resolution
• /doctor - Diagnose and fix database/system issues (runs diagnostic check by default)
  • /doctor clean - Clean orphaned database records and PDF files
  • /doctor help - Show doctor command help
• /config - Configuration management for models, API keys, and sync settings
  • /config show - Show all current configuration
  • /config model <model> - Set OpenAI model (gpt-4o, gpt-4o-mini, gpt-3.5-turbo, etc.)
  • /config openai_api_key <key> - Set OpenAI API key
  • /config max-tokens <number> - Set OpenAI max tokens (default: 4000)
  • /config temperature <number> - Set OpenAI temperature (default: 0.7)
  • /config remote <path> - Set remote sync path for OneDrive
  • /config auto-sync enable|disable - Enable/disable automatic sync after edits
  • /config auto-sync-interval <seconds> - Set auto-sync interval (default: 5s)
  • /config pdf-pages <number> - Set PDF pages limit for chat/summarize operations
  • /config help - Show configuration help
• /version - Version management and updates
  • /version check - Check for available updates
  • /version update - Update to the latest version (if possible)
  • /version info - Show detailed version information
• /log - Show activity log panel

• arXiv: Add papers using arXiv IDs (e.g., 2307.10635)
• DBLP: Import papers from DBLP URLs
• OpenReview: Add papers using OpenReview IDs

• PDF: Local PDF files with automatic metadata extraction
• BibTeX: Import from .bib files
• RIS: Import from .ris files
• Manual Entry: Add papers manually with custom metadata

PaperCLI will prompt you for configuration on first run if needed. You can set up configuration in two ways:

# Required for AI features
export OPENAI_API_KEY=your_openai_api_key_here
# Optional settings
export OPENAI_MODEL=gpt-4o # defaults to gpt-4o
export OPENAI_MAX_TOKENS=4000 # defaults to 4000
export OPENAI_TEMPERATURE=0.7 # defaults to 0.7
export PAPERCLI_DATA_DIR=/path/to/data # defaults to ~/.papercli
export PAPERCLI_PDF_PAGES=10 # defaults to 10 pages for chat/summarize
export PAPERCLI_THEME=textual-dark # defaults to textual-dark
export PAPERCLI_REMOTE_PATH=/path/to/remote # OneDrive sync path
export PAPERCLI_AUTO_SYNC=true # defaults to false
export PAPERCLI_AUTO_SYNC_INTERVAL=5 # defaults to 5 seconds

Create a .env file in your current directory or data directory (~/.papercli/):

# OpenAI API key (required for local chat interface and summarization)
OPENAI_API_KEY=your_openai_api_key_here
# OpenAI model for chat and summarization (optional, defaults to gpt-4o)
OPENAI_MODEL=gpt-4o
# OpenAI API settings (optional)
OPENAI_MAX_TOKENS=4000
OPENAI_TEMPERATURE=0.7
# Data directory for database and PDFs (optional, defaults to ~/.papercli)
PAPERCLI_DATA_DIR=/path/to/your/papercli/data
# PDF pages limit for chat and summarization (optional, defaults to 10)
PAPERCLI_PDF_PAGES=10
# UI theme (optional, defaults to textual-dark)
PAPERCLI_THEME=textual-dark
# OneDrive sync settings (optional)
PAPERCLI_REMOTE_PATH=/path/to/onedrive/folder
PAPERCLI_AUTO_SYNC=false
PAPERCLI_AUTO_SYNC_INTERVAL=5

PaperCLI stores all data in a single directory (default: ~/.papercli/):

• papers.db - SQLite database with paper metadata
• pdfs/ - Downloaded PDF files
• version_config.json - Version update settings

The application will check for .env files in this order:

1. Current working directory
2. Data directory (~/.papercli/ or $PAPERCLI_DATA_DIR)

PaperCLI uses a SQLite database with the following main entities:

• Papers: UUID (unique identifier), title, abstract, venue, year, authors, collections, PDF path, notes
• Authors: Name, email, affiliation with ordered relationships
• Collections: Custom paper groupings
• Metadata: DOI, preprint IDs, URLs, paper types

PaperCLI uses Alembic for database schema migrations. When you upgrade to a new version:

• Database schema is automatically upgraded on first sync
• The upgrade process is safe and preserves all your data
• If using OneDrive sync, both local and remote databases must be accessible during migration

Note: As of v2.2.0, papers are identified by UUID instead of title. This enables:

• Editing paper titles without creating duplicates during sync
• More reliable synchronization across devices
• Better handling of papers with similar titles

• ↑/↓ - Navigate the paper list or scroll panels
• PageUp/PageDown - Scroll panels by a full page
• Space - Toggle selection for a paper (only in /select mode)
• Enter - Execute a command from the input bar
• ESC - Close panels
• Ctrl+C - Clear input or exit application
• Tab - Trigger and cycle through auto-completions

• F1 - Add paper dialog
• F2 - Open paper PDF
• F3 - Show paper details
• F4 - Chat with AI about paper
• F5 - Edit paper metadata
• F6 - Delete paper
• F7 - Manage collections
• F8 - Filter papers
• F9 - Show all papers
• F10 - Sort papers
• F11 - Toggle selection mode
• F12 - Clear selection

When using the local chat interface (/chat):

• Enter - Send message
• ↑/↓ - Scroll chat display
• PageUp/PageDown - Scroll chat display by page
• Ctrl+S - Save chat to file
• Esc - Close chat interface

1. PDF Download Failures:

   /doctor
   

2. Database Issues:

   /doctor clean
   

3. Missing Dependencies:

   pip install -r requirements.txt

• Check /log panel for recent errors
• Use /doctor for system health checks
• Log files are stored in ~/.papercli/logs/

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Commit your changes: git commit -m "feat: add new feature"
5. Push to the branch: git push origin feature-name
6. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

• Issues: Report bugs and request features on GitHub Issues
• Documentation: Run /help within the application
• Discussions: Join discussions on GitHub Discussions

PaperCLI - Streamline your research workflow with powerful command-line paper management.