docs: add docs
This commit is contained in:
+288
@@ -0,0 +1,288 @@
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user