scholar

An agent-native CLI for research papers. Search arXiv, read abstracts, and trace citations from the terminal — with a local SQLite mirror for instant, offline repeat lookups.

Built in the Printing Press style: token-efficient output, a local data mirror, a companion Claude Code skill, and an MCP server. No API key required; no third-party Python dependencies.

Install

# Isolated install (recommended) — gives you `scholar` and `scholar-mcp`
pipx install "git+https://github.com/saakshigupta2002/scholar-cli"

# Or, from a clone:
pip install -e .

# Or, run straight from source without installing:
python3 -m scholar search "graph neural networks"

Usage

scholar search "diffusion models protein design"   # search arXiv
scholar get 1706.03762                              # one paper + abstract
scholar cites 1706.03762                            # who cited it
scholar cites 1706.03762 --references               # what it cites
scholar list                                        # cached papers (offline)

Agent-friendly flags

scholar --json search "mixture of experts" --max 5         # structured output
scholar --json --select id,title search "rag" --max 10     # only the fields you need

Flag	Purpose
--json	Structured JSON for agents/scripts
--select a,b,c	Keep only these fields (saves tokens)
--max N	Number of results
--cat cs.LG	Limit a search to a category
--sort relevance|submitted|updated	Result ordering

Exit codes: 0 ok · 2 usage · 3 not found · 4 upstream/network error.

How it's built

Piece	Job
scholar/arxiv.py	arXiv client (search + fetch by id)
scholar/semscholar.py	Semantic Scholar client (citations)
scholar/db.py	Local SQLite mirror (~/.scholar/scholar.db)
scholar/output.py	Human table vs --json / --select
scholar/cli.py	Command parsing and dispatch
scholar/mcp_server.py	MCP server (stdio) exposing the same tools
cli-skills/pp-scholar/SKILL.md	Claude Code skill that drives the CLI

MCP

The same operations are available over MCP for agents that prefer it:

{ "mcpServers": { "scholar": { "command": "scholar-mcp" } } }

Data sources

• arXiv API — search and metadata (free, open).
• Semantic Scholar Graph API — citations (free).

Please be polite to both APIs (they are free and rate-limited).

License

Apache-2.0.