Content
# 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](https://printingpress.dev/) 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
```bash
# 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
```bash
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
```bash
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:
```json
{ "mcpServers": { "scholar": { "command": "scholar-mcp" } } }
```
## Data sources
- [arXiv API](https://info.arxiv.org/help/api/) — search and metadata (free, open).
- [Semantic Scholar Graph API](https://api.semanticscholar.org/api-docs/graph) — citations (free).
Please be polite to both APIs (they are free and rate-limited).
## License
Apache-2.0.
