paperlib/docs/cli.md

CLI Reference

This document describes all available commands in the paperlib CLI.

Global Options

All commands support these global options:

• --help, -h: Show help message
• --version: Show version information

Many commands also support:

• --library, -L: Specify library root directory (default: current directory)
• --json: Output machine-readable JSON instead of human-readable format

Commands

paperlib init [PATH]

Initialize a paper library directory structure.

Arguments:

• PATH: Directory to initialize (default: current directory)

Examples:

# Initialize library in current directory
paperlib init

# Initialize library in specific directory
paperlib init /path/to/my/papers

# Initialize and create parent directories
paperlib init ~/Documents/research/papers

Behavior:

• Creates standard directory structure (config/, papers/, db/, etc.)
• Safe to run multiple times (idempotent)
• Creates parent directories if they don't exist

---

paperlib import

Import papers into the library from various sources.

Required (one of):

• --pdf PATH: Import a local PDF file
• --arxiv ID: Import paper from arXiv by ID or URL

Options:

• --title TEXT: Override paper title (for local PDFs)
• --notes TEXT: Add notes about the paper
• --tags TAG1 TAG2: Add tags to the paper
• --library PATH: Specify library directory

Examples:

# Import local PDF
paperlib import --pdf paper.pdf --title "My Research" --tags ml ai

# Import from arXiv
paperlib import --arxiv 2212.06340

# Import with arXiv URL
paperlib import --arxiv https://arxiv.org/abs/2212.06340

# Import to specific library
paperlib import --pdf paper.pdf --library ~/research

Behavior:

• Generates stable paper ID based on content (local) or arXiv ID
• Copies PDF to structured storage location
• Creates meta.json with paper metadata
• Prevents duplicate imports (same content/ID)
• Indexes paper in search database

---

paperlib list

List all papers in the library with their current status.

Options:

• --library PATH: Specify library directory
• --json: Output in JSON format

Examples:

# List all papers
paperlib list

# List papers in specific library
paperlib list --library ~/research

# Get machine-readable output
paperlib list --json

Output Format:

Found 3 papers:

📄 arxiv-2212_06340
   The new discontinuous Galerkin methods based numerical relativity program Nmesh
   By: Wolfgang Tichy, Liwei Ji, Ananya Adhikari (+2 more)
   Categories: gr-qc

⏳ local-a1b2c3d4e5f6
   Machine Learning Applications in Physics
   Categories: cs.AI, physics.comp-ph

Status Indicators:

• ⏳ Paper imported, conversion pending
• 📄 PDF converted to Markdown
• 📝 AI summary generated
• ❌ Conversion or processing failed

---

paperlib show PAPER_ID

Show detailed information about a specific paper.

Arguments:

• PAPER_ID: The unique paper identifier

Options:

• --library PATH: Specify library directory
• --json: Output in JSON format

Examples:

# Show paper details
paperlib show arxiv-2212_06340

# Show with JSON output
paperlib show local-a1b2c3d4 --json

Output includes:

• All metadata fields
• Processing status
• File locations and existence
• Import timestamp
• Tags and notes

---

paperlib convert

Convert papers from PDF to Markdown using MinerU.

Options:

• --library PATH: Specify library directory
• --paper-id ID: Convert specific paper only

Examples:

# Convert all pending papers
paperlib convert

# Convert specific paper
paperlib convert --paper-id arxiv-2212_06340

# Convert in specific library
paperlib convert --library ~/research

Behavior:

• Processes papers with conversion_status: pending
• Uses MinerU for PDF to Markdown conversion
• Updates metadata with conversion status
• Creates conversion logs in logs/ directory
• Handles conversion failures gracefully

---

paperlib reindex

Rebuild the search index from stored paper metadata.

Options:

• --library PATH: Specify library directory

Examples:

# Rebuild index
paperlib reindex

# Rebuild index for specific library
paperlib reindex --library ~/research

Behavior:

• Clears existing SQLite database
• Scans all meta.json files in papers/ directory
• Rebuilds full-text search index
• Reports statistics on completion
• Safe to run anytime (repairs corrupted index)

---

paperlib status

Show library configuration and layout information.

Options:

• --library PATH: Specify library directory
• --json: Output in JSON format

Examples:

# Show current library status
paperlib status

# Show specific library status
paperlib status --library ~/research

Output:

root: /home/user/papers
config: /home/user/papers/config/config.toml
database: /home/user/papers/db/paperlib.sqlite3
papers: /home/user/papers/papers
inbox: /home/user/papers/inbox
cache: /home/user/papers/cache

---

Future Commands

These commands are planned but not yet implemented:

paperlib search QUERY

Search papers by content and metadata.

paperlib summarize [PAPER_ID]

Generate AI summaries for papers.

paperlib export FORMAT

Export papers in various formats.

paperlib doctor

Diagnose and repair library issues.

---

Exit Codes

paperlib commands return standard exit codes:

• 0: Success
• 1: General error (file not found, invalid arguments, etc.)
• 2: Command line argument error

Configuration

paperlib looks for configuration in these locations (in order):

1. $LIBRARY_ROOT/config/config.toml
2. ~/.config/paperlib/config.toml
3. Built-in defaults

JSON Output Format

When using --json, commands output structured data suitable for programmatic consumption:

{
  "papers": [
    {
      "paper_id": "arxiv-2212_06340",
      "title": "Example Paper",
      "authors": ["Alice Smith", "Bob Jones"],
      "conversion_status": "success",
      "imported_at": "2024-01-15T10:30:00"
    }
  ],
  "total": 1
}

This format is stable across paperlib versions for reliable automation.