Scholar CLI

English | 中文

Agent-oriented academic research CLI, distributed as a single Rust binary.

Status: v0.1.0 — PDF download MVP (legal OA + arXiv)
Design: docs/design/scholar-cli.md

Features (v1)

• Download PDFs by DOI or arXiv ID
• Multi-source race: Unpaywall, OpenAlex, Semantic Scholar, DOAJ, Crossref, publisher direct
• Default strategy legal_only (no grey sources in default build)
• Agent-first: JSON stdout, stable exit codes, non-interactive
• Result cache, auto-rename, batch + resume, EMA source scores
• Config under ~/.scholar/; proxy via config or HTTP(S)_PROXY

Quick start

Download the archive for your operating system and CPU from the latest GitHub Release. Extract it, then place scholar (macOS/Linux) or scholar.exe (Windows) in a directory on your PATH.

scholar doctor -q
scholar pdf get 1706.03762 -o ./papers -q
scholar config set email you@example.com
scholar pdf get 10.1038/nature12373 -o ./papers -q

See the detailed usage guide for platform selection, checksum verification, batch downloads, configuration, proxies, caching, JSON output, exit codes, and troubleshooting.

Workspace

scholar/
├── crates/
│   ├── scholar/        # CLI binary
│   ├── scholar-core/   # identifiers, config, contract, exit
│   └── scholar-pdf/    # HTTP, sources, race, cache, batch
├── fixtures/
└── .github/workflows/ci.yml

v1 acceptance (appendix B)

1. Single binary, no Python
2. pdf get + Contract v1 JSON + correct exit
3. arXiv + arXiv DOI L0
4. Legal sources incl. DOAJ / Crossref / publisher prefix table
5. Default no grey; scihub_* → exit 2
6. No email → skip Unpaywall (doctor warn)
7. PDF validation (is_pdf_file / suspicious)
8. Non-interactive (no stdin prompts)
9. doctor / strategies JSON
10. Release artifact without grey

Optional: Sci-Hub (grey-sources)

Sci-Hub is not in the default build. It is dual-gated:

1. Compile with feature grey-sources
2. Runtime scihub_enabled=true

cargo build -p scholar --release --features grey-sources
./target/release/scholar config set scihub_enabled true
# optional mirrors (comma-separated)
# ./target/release/scholar config set scihub_domains https://sci-hub.se,https://sci-hub.st

./target/release/scholar pdf get 10.1038/nature12373 --strategy scihub_first -o ./papers -q
# or: --strategy scihub_only | grey_only | fastest

Compliance: You are responsible for complying with applicable laws and institutional policies. Default legal_only never uses grey sources.

License

Apache-2.0