A terminal-first bibliometric analysis CLI tool — scan, import, analyze, and visualize your literature collection.
Citationer is a lightweight, local-first, zero-config CLI tool for researchers. Drop into a directory with bibliographic export files, run a single command, and get a complete literature analysis — from descriptive statistics with terminal charts to knowledge graphs and AI-powered topic labeling.
| Category | Capability |
|---|---|
| 🔍 7 Parsers | CNKI, WoS, Scopus, PubMed, CSSCI, BibTeX, RIS — auto-detection |
| 📊 Descriptive Stats | Yearly trends, top journals/authors/institutions, h-index — with terminal charts |
| 📈 Terminal Charts | Braille line charts + Unicode bar charts rendered directly in terminal |
| 🔗 Network Analysis | Keyword co-occurrence, author/institution collaboration, co-citation, bibliographic coupling |
| 📝 Text Mining | Tokenization, keyword frequency, LDA/NMF topic modeling, TF-IDF summarization, clustering |
| 🤖 LLM-Powered AI | Topic labeling, literature review, trend identification, classification — DeepSeek/OpenAI/Ollama |
| 🆕 Interactive Mode | Step-by-step wizard (citationer interactive) |
| 🆕 Pipeline Runner | Declarative YAML pipeline (citationer run pipeline.yaml) |
| ⚙ Configurable | CLI-driven config, env-var support, multi-provider LLM |
| 🎨 Rich Terminal | Color tables, progress bars, interactive HTML network graphs (Plotly) |
| 📦 Pipe-friendly | JSON/CSV/GEXF/GraphML export — works with grep, jq, Gephi, Cytoscape |
# Recommended: isolated install via pipx
pipx install citationer
# Or via pip
pip install citationer
# With all optional dependencies (NLP, network, AI, viz)
pip install "citationer[all]"
# From source
git clone https://github.com/JasonCENG/citationer.git
cd citationer
pip install --no-build-isolation -e ".[all,dev]"# 1. Check version
citationer --version
# 2. Navigate to your literature directory
cd /path/to/literature
# 2. Scan for bibliographic files
citationer scan
# 3. Import into the local database (auto-clears old data)
citationer import
# 4. Clean & deduplicate
citationer clean
# 5. View the overview dashboard
citationer stats overviewcitationer scan # Scan directory for bibliographic files
citationer status # Quick status check
citationer import # Import files (clears old data by default)
citationer import --keep # Append to existing data
citationer clean # Validate & deduplicate recordscitationer stats overview # Dashboard: totals, years, h-index, languages
citationer stats yearly # Braille line chart
citationer stats yearly --cumulative # Dual bar+line chart
citationer stats yearly --table # Data table
citationer stats journals --top 20 # Horizontal bar chart
citationer stats authors --top 20 # Bar chart + Price's Law core authors
citationer stats institutions --top 20 # Bar chartcitationer text preprocess # Tokenize + language detection
citationer text keywords --top 30 # Keyword frequency
citationer text keywords --per-year # Keyword × year heatmap
citationer text topics --method lda # LDA topic modeling
citationer text topics --method nmf # NMF topic modeling
citationer text summarize # TF-IDF extractive summary
citationer text cluster --method kmeans # Document clusteringcitationer trend hotspots --top 30 # Keyword burst detection
citationer trend hotspots --gamma 0.5 # More sensitive (detects weaker bursts)
citationer trend strategy --top 50 # Strategic diagram (centrality × density)citationer export csv -o data.csv # Export to CSV
citationer export json -o data.json # Export to JSON
citationer export bibtex -o refs.bib # Export to BibTeXcitationer report quick -o report.md # Generate Markdown report
citationer report quick -o report.html # HTML report
citationer report quick --enhance -o r.md # LLM-enhanced report
citationer report custom cfg.yaml -o r.md # Custom YAML-configured reportcitationer network keywords --top 50 --threshold 3 # Co-occurrence network
citationer network coauthors --min-papers 2 # Author collaboration
citationer network coauthors --type institutions # Institution collaboration
citationer network cocitation --top 30 # Co-citation analysis
citationer network coupling --top 30 # Bibliographic coupling
# Export formats: csv, gexf, graphml, html (interactive)
citationer network keywords --output-format gexf --output graph.gexf
citationer network coauthors --viz --output network.html# Configure your LLM first
citationer config set llm.api_key sk-your-key
citationer config set llm.model deepseek-chat
citationer ai topics --auto-label # Auto-label LDA topics
citationer ai summarize # Generate literature review (200-500 words)
citationer ai trends # Identify research trends & gaps
citationer ai classify # Multi-dimensional classification
citationer ai info # View LLM config & cache stats
# Preview without API call
citationer ai summarize --dry-runcitationer interactive # Step-by-step guided analysis wizardcitationer run pipeline.yaml # Execute declarative YAML pipelinecitationer config show # View all settings
citationer config set llm.api_key sk-xxx # Set API key
citationer config set llm.model gpt-4o # Change model
citationer config set llm.base_url https://api.openai.com/v1 # Change provider
citationer config init # Initialize config file with defaultsCitationer supports any OpenAI-compatible API. Edit .citationer/config.yaml or use env vars:
# .citationer/config.yaml
llm:
api_key: "sk-xxx"
model: "deepseek-chat"
base_url: "https://api.deepseek.com"
temperature: 0.3
max_tokens: 4096| Provider | base_url |
|---|---|
| DeepSeek | https://api.deepseek.com |
| OpenAI | https://api.openai.com/v1 |
| Ollama (local) | http://localhost:11434/v1 |
Environment variables override the config file: CITATIONER_LLM_API_KEY, CITATIONER_LLM_MODEL, etc.
| Source | Format | Extensions | Status |
|---|---|---|---|
| Web of Science | Plain text / Tab-delimited / Excel | .txt, .ciw, .xlsx, .xls |
✅ |
| CNKI (知网) | Excel export | .xlsx |
✅ |
| Scopus | CSV / Excel | .csv, .xlsx |
✅ |
| PubMed | XML / MEDLINE | .xml, .nbib |
✅ |
| CSSCI | Excel / Text | .xlsx, .txt, .csv |
✅ |
| BibTeX | Generic | .bib |
✅ |
| RIS | Generic | .ris, .txt |
✅ |
# Install with all dependencies
pip install --no-build-isolation -e ".[all,dev]"
# Run tests
pytest tests/ -v
# Lint & type check
ruff check src/ tests/
mypy src/ --ignore-missing-imports
# Coverage report
pytest tests/ --cov=src/citationer --cov-report=term-missing- Wiki Home — Links to all docs
- Handbook — Full user manual (English)
- 用户手册 — 中文用户手册
- PRD v2.1 — Terminal charts
- PRD v2.0 — Full requirements doc (Phase 1–5)
- PRD v1.0 — Original PRD
- PRD v1.0 — Original PRD (historical)
MIT © Jason Yu