google-scholar

# Google Scholar CLI (scholar)

Search Google Scholar for academic papers via the `scholar` command-line tool.

**Requires:** `scholar` on PATH (`~/.local/bin/scholar` → `~/projects/google-scholar-cli/scholar`)

**Check:** `command -v scholar || echo "MISSING: scholar CLI not installed"`

## IRON LAW: No Hallucinated Metadata

**NEVER fabricate paper titles, authors, journals, years, or abstracts from memory.**

When the user asks about a specific paper or needs citation details:

```
User mentions a paper
    ↓
Do you have the exact metadata from a scholar command in this session?
    ↓
YES → Use that data
NO  → Run scholar search/lookup --bibtex FIRST, then report
```

### Metadata Facts

- Training-data paper metadata is unreliable even for famous papers — wrong years, missing co-authors, garbled titles. Presenting remembered metadata is an unverified claim presented as fact; run `scholar lookup "title" --bibtex` first, then report.
- `--bibtex` adds seconds, not minutes, and the BibTeX includes the abstract — reconstructing either from memory is counterproductive on its own terms.

### Red Flags

- **About to type a paper title from memory** → STOP. Run `scholar lookup`.
- **About to list authors without a source** → STOP. Run `--bibtex`.
- **Saying "published in" without verification** → STOP. Check the BibTeX.
- **Writing an abstract from memory** → STOP. BibTeX includes the abstract.

## Authentication

Before first use, authenticate by extracting cookies from an active Chrome session:

```bash
# Chrome must be running with remote debugging enabled
scholar auth --port 9222
```

Cookies are stored in `~/.google-scholar/cookies` (mode 0600).

## Core Commands

### Scholar Labs Search (AI-Enhanced)

Natural language search using Google Scholar Labs API:

```bash
# One-shot search
scholar search "what are the key papers on attention mechanisms"

# JSON output for parsing
scholar search "corporate disclosure and information asymmetry" --json

# With BibTeX citations (includes abstracts)
scholar search "attention is all you need" --bibtex

# Download PDFs for results with full-text links
scholar search "transformer architectures" --download

# Interactive multi-turn mode (follow-up questions)
scholar search --interactive
```

### Traditional Keyword Search

Standard Google Scholar full-text search:

```bash
# Keyword search
scholar lookup "machine learning transformers"

# Author search
scholar lookup "author:shleifer disclosure" --json

# With BibTeX
scholar lookup "asset pricing" --bibtex

# With PDF download
scholar lookup "deep learning" --download
```

### Cite (BibTeX by Cluster ID)

Fetch BibTeX directly when you already have a cluster ID from search results:

```bash
# Single paper
scholar cite 5Gohgn6QFikJ

# Multiple papers, JSON output
scholar cite 5Gohgn6QFikJ 8409835334886051453 --json
```

### Download (Single PDF)

**Note:** `--download` works for open-access PDFs (arXiv, NBER, etc.) but is unreliable for papers behind library link resolvers (institutional access). For paywalled papers, return the URL and let the user download manually.

```bash
scholar download "https://arxiv.org/pdf/1706.03762" --output attention.pdf
```

## Quick Reference

| Need | Command |
|------|---------|
| Natural language question | `scholar search "question"` |
| Keyword/author search | `scholar lookup "keywords"` |
| BibTeX citations | Add `--bibtex` to search/lookup |
| BibTeX by cluster ID | `scholar cite <clusterId>` |
| Download PDFs | Add `--download` to search/lookup |
| Download single PDF | `scholar download "url" --output file.pdf` |
| JSON output | Add `--json` to any command |
| Interactive follow-ups | `scholar search --interactive` |
| Re-authenticate | `scholar auth` |

## Decision Tree: Which Command?

```
Do you have a cluster ID already?
  YES → scholar cite <clusterId>
  NO  ↓
Do you have a natural language research question?
  YES → scholar search "question"
  NO  ↓
Do you need keyword-exact or author-specific results?
  YES → scholar lookup "author:name keyword"
  NO  ↓
Do you want follow-up refinement?
  YES → scholar search --interactive
```

**When to add flags:**

```
Need citation metadata (authors, journal, year, abstract)?
  YES → Add --bibtex
Need to download the PDF (open-access only)?
  YES → Add --download (unreliable for paywalled papers — return the URL instead)
Need machine-readable output?
  YES → Add --json
```

## Verified Paper Information Workflow

When presenting paper information to the user, follow this workflow:

```
1. Run scholar search/lookup with --bibtex
2. Parse BibTeX fields for authoritative metadata:
   - title, author, journal/booktitle, year, abstract
3. Present ONLY the fields returned by BibTeX
4. If BibTeX is missing a field, say "not available" — do NOT fill from memory
```

**BibTeX includes abstracts:** The `--bibtex` flag injects the snippet as an `abstract` field in the BibTeX entry. Use this instead of generating abstracts.

## Output Format

**Table output (default):** Columns for #, Title, Authors, Year, Cited, Journal, followed by snippets and URLs.

**JSON output (`--json`):** Array of `ScholarResult` objects:

```json
{
  "title": "Paper Title",
  "authors": "Author A, Author B",
  "journal": "Journal Name",
  "year": "2024",
  "citations": 150,
  "snippet": "Abstract excerpt...",
  "url": "https://...",
  "pdfUrl": "https://... or null",
  "clusterId": "12345",
  "position": 1
}
```

**BibTeX output (`--bibtex`):** Standard BibTeX entries with abstract field:

```bibtex
@article{key,
  title={Paper Title},
  author={Author, A and Author, B},
  journal={Journal Name},
  year={2024},
  abstract={Abstract text from Google Scholar snippet...}
}
```

## Domain Knowledge Integration

When searching Google Scholar, ALWAYS consult the domain knowledge file first:

**File:** `domain-knowledge.local.md` (relative to this skill's base directory)

This file contains the user's curated list of trusted journals, authors, and research groups. Use it to:

1. **Prioritize results** from known-good journals and authors
2. **Flag unfamiliar sources** - if a result is from an unknown journal, note it
3. **Suggest related searches** - use known authors to refine queries
4. **Assess quality** - weight results higher when they appear in trusted venues

### How to Use Domain Knowledge

```
User asks: "find papers on corporate disclosure"
    ↓
1. Read domain-knowledge.local.md
2. Run scholar search/lookup
3. Cross-reference results against trusted journals/authors
4. Present results with quality signals:
   - ★ = from trusted journal or by trusted author
   - Results from unknown sources shown without star
```

## Operational Rules

1. **No hallucinated metadata** — NEVER cite title/author/journal/year/abstract from memory. Use `--bibtex` or `scholar cite` to get verified data.
2. **Scholar is for discovery** — Use it to find new papers, not to read them
3. **Always use `--json`** when results will be processed programmatically
4. **Use `--bibtex` when presenting papers** — It provides verified author, journal, year, and abstract fields
5. **Cross-reference domain knowledge** — Always check trusted journals/authors
6. **Auth required** — If search fails with auth errors, re-run `scholar auth`
7. **Rate limits** — Google Scholar may rate-limit; space out rapid queries