Scholar sidekick cli

Scholar Sidekick (CLI) — Citations, Retraction & Open-Access from the terminal

Turn a scholarly identifier into a formatted citation, a bibliography file, or an integrity check (retraction / open-access / fabrication) by running the scholar command. The CLI is a thin wrapper over the public Scholar Sidekick REST API. No API key required for the free, rate-limited tier — and ergonomic subcommands mean you don't hand-build JSON request bodies.

Sibling skills, same capabilities: use scholar-sidekick-api if there's no Node runtime (plain curl), or scholar-sidekick-mcp if an MCP host is connected. This skill is the typed-CLI path for Node ≥20.

When to Use

• The user has an identifier (DOI, PMID, PMCID, ISBN, arXiv, ISSN, ADS bibcode, WHO IRIS URL) and wants metadata, a formatted citation, or a bibliography file, and the environment has Node ≥20.
• "Cite this in APA/Vancouver/Chicago…", "give me a BibTeX/RIS file", "export these refs to a file".
• "Has this been retracted?", "is this open access?", "is this citation real / did you make it up?"
• "Audit my bibliography" / "check all the references in this .bib file" — a whole reference list at once.
• Batch jobs: several identifiers at once, or streaming results as they resolve.
• Do NOT use to search for papers by topic — that's discovery (see the arxiv skill). This assumes you already have an identifier.
• Prefer scholar-sidekick-api instead when there is no Node runtime, or scholar-sidekick-mcp when an MCP host is connected.

Install

The CLI ships on npm as scholar-sidekick-cli (bin: scholar). Requires Node.js ≥ 20.

# zero-install, per-invocation
npx -y scholar-sidekick-cli format 10.1038/nphys1170 --style apa

# or install globally and call `scholar`
npm install -g scholar-sidekick-cli
scholar health

The examples below use scholar; substitute npx -y scholar-sidekick-cli if you didn't install globally.

Commands

Command	What it does	Batch?
format <ids...>	Format identifiers into a citation style. --style, --lang, --footnote, --output text|html|json.	yes
resolve <ids...>	Resolve identifiers to bibliographic metadata (CSL/Biblio JSON).	yes
export <ids...>	Export to a file format: --format bib|ris|csv|csl|endnote-xml|endnote-refer|refworks|medline|zotero-rdf|txt. Raw file content on stdout.	yes
format-items	Format pre-resolved items from --file <json> or stdin (a JSON array).	—
stream <ids...>	Format a batch, streaming each result as NDJSON as it resolves.	yes
verify	Verify a claimed citation against the record at its identifier. --title (required) + an identifier flag (--doi, --pmid, …).	no
audit [file]	Audit a whole bibliography (BibTeX/RIS/CSL-JSON file, or stdin): per-entry fabrication check + retraction status, plus a corpus summary. --format, --no-retraction, --fail-on-issues. Max 25 entries.	file
retraction <id>	Retraction / correction / expression-of-concern status (Crossref / Retraction Watch). Alias context: single id.	no
oa <id>	Open-access status and best legal copy (Unpaywall). Alias: open-access.	no
styles [query]	List/search available CSL citation styles (paginated).	—
health	Service liveness and diagnostics.	—

format, resolve, export, and stream accept multiple identifiers (space-, comma-, or newline-separated). verify, retraction, and oa take a single identifier; audit takes a bibliography file (or stdin) rather than identifiers. Run scholar <command> --help for the full option list.

Procedure

Format a citation

scholar format 10.1038/nphys1170 --style vancouver
scholar format 10.1038/nphys1170 PMID:30049270 --style apa   # batch

• --style: vancouver (default), ama, apa, ieee, cse, or any CSL style ID (chicago-author-date, harvard-cite-them-right, nature, the-lancet, …). Use scholar styles <query> to discover IDs.
• Pass identifiers verbatim — PMID:, arXiv:, ISBN hyphens, and https://doi.org/… are all tolerated.

Export a bibliography file

scholar export 10.1038/nphys1170 PMID:30049270 --format ris > refs.ris

export writes the raw file content to stdout, so redirect it straight to a file. Formats: bib, ris, csv, csl, endnote-xml, endnote-refer, refworks, medline, zotero-rdf, txt.

Check retraction / open access

scholar retraction 10.1016/S0140-6736(97)11096-0
scholar oa 10.1371/journal.pone.0173664

One identifier per call. Books/ISBNs have no DOI, so these report a "no DOI" result.

Verify a claimed citation (catch fabrication)

scholar verify --title "The title exactly as cited" --doi 10.1016/S0140-6736(26)00603-3

--title is required plus an identifier flag. Verdict ∈ matched / mismatch / ambiguous / not_found:

• mismatch — identifier resolves but the title doesn't: the dominant AI-fabrication pattern (real DOI + invented title; Topaz et al., Lancet 2026).
• ambiguous — identifier resolves to one paper but the claimed title matches a different real paper (wrong-identifier error, not fabrication).

Use this for "is this citation real?", not a plain format/resolve. Add --fail-on-mismatch to make mismatch/not_found exit non-zero for scripting/CI.

Audit a whole bibliography (batch fabrication + retraction check)

scholar audit refs.bib                       # BibTeX/RIS/CSL-JSON, format auto-detected
cat refs.ris | scholar audit                 # or pipe via stdin
scholar audit refs.bib --json | jq '.summary'

The batch counterpart to verify: every entry gets the fabrication check plus a retraction lookup, and the command prints a per-entry verdict table and a corpus summary (total / matched / mismatch / ambiguous / not_found / errored / retracted). Flags: --format bibtex|ris|csl-json overrides auto-detection, --no-retraction skips the retraction lookup, --fail-on-issues exits non-zero when any entry is mismatch, not_found, or retracted (for scripting/CI). Max 25 entries per call; one bad entry becomes status: "error" without failing the batch. This audits citation identity — it does not check whether each source supports the claim it is cited for.

Error-recovery loop (verify). Correctness matters here, so don't guess on failure:

1. Run scholar verify ….
2. Check the exit code. 0 → trust the printed verdict.
3. On non-zero, re-run with --json and read the verdict/error field — distinguish a real mismatch/not_found (report it as such) from a network/usage error (code 2/3, retry or fix flags).
4. Report exactly what the CLI returned. Never emit a matched/genuine verdict the tool did not produce.

Output & parsing (for agents)

• Default output is human-readable text. Pass --json to any command to get the raw API JSON — parse that, don't scrape the pretty text:

  scholar resolve 10.1016/S0140-6736(26)00603-3 --json | jq '.[0].title'
  

• A dim provenance footer (request id, cache status, style, version) goes to stderr, so it never pollutes piped stdout. Suppress it with --quiet. Colour auto-disables off-TTY / with NO_COLOR / --no-color.

Authentication, limits & exit codes

Works anonymously at the free, rate-limited tier — fine for normal agent use. Optional ssk_ or RapidAPI keys raise limits. The CLI uses standard exit codes (0 ok, 1 API error, 2 network/timeout, 3 usage error). Full detail — keys, --base-url/--timeout, and the exit-code table — is in REFERENCE.md.

Always check the exit code; on non-zero, report the failure — never invent a citation, retraction status, OA verdict, or a matched verdict.

Pitfalls

• Needs Node ≥20. If unavailable, use the scholar-sidekick-api skill (plain curl) instead.
• Pass identifiers verbatim; don't strip prefixes.
• --json is what you parse; the default text and the stderr footer are for humans.
• verify/retraction/oa are single-identifier; only format/resolve/export/stream batch. To check a whole reference list in one call, use audit with a file (not identifiers).
• Under a RapidAPI key, format-items/stream/styles aren't available — run those anonymously or with an ssk_ key.

Verification

• scholar health (or --json) returns an ok: true payload.
• A good scholar format … --json response has a non-empty formatted citation in the JSON.