Check whether a paper is retracted, why, and what the current research says now — keyless, over Crossref and OpenAlex.
Retraction Checker turns Crossref's embedded Retraction Watch data into a one-shot verdict: is this DOI or PMID retracted, when, why, and where is the notice. It batch-scans reading lists and .bib files, finds citation-ranked superseding research via OpenAlex, and watches a topic or library for newly-announced retractions. Fully keyless.
Learn more at Retraction Checker.
Created by @laci141 (laci141).
Quick Start
# Confirm the CLI and Crossref reachability before checking papers
retraction-checker-pp-cli doctor --dry-run
# Check a single DOI for retraction status
retraction-checker-pp-cli check 10.1016/j.micpro.2020.103768 --json
# Flag retracted entries across a bibliography
retraction-checker-pp-cli scan refs.bib --json
Unique Features
These capabilities aren't available in any other tool for this API.
Retraction intelligence
-
check — Tell whether a paper (by DOI or PMID) has been retracted, when, why, and where the notice is.
Agents citing a paper should verify it is not retracted before relying on it.
retraction-checker-pp-cli check 10.1016/j.micpro.2020.103768 --json
-
scan — Batch-check a reading list or .bib file and flag every retracted entry.
Catches retracted citations across a whole manuscript or literature review at once.
retraction-checker-pp-cli scan refs.bib --json
-
superseded — For a retracted or older paper, find related more-recent research on the same topic, ranked by citation count.
When a paper is retracted, the agent still needs the current best evidence on the topic.
retraction-checker-pp-cli superseded 10.1016/j.micpro.2020.103768 --json
Local state that compounds
-
watch — Monitor a topic or reading list for newly-announced retractions since the last run.
Surfaces new retractions in a field or personal library without re-reading everything.
retraction-checker-pp-cli watch "machine learning" --json
Recipes
Check a DOI
retraction-checker-pp-cli check 10.1016/j.micpro.2020.103768 --json
Returns retraction status, date, reason source, and notice reference for one paper.
Audit a bibliography
retraction-checker-pp-cli scan reading-list.txt --agent --select doi,retracted,reason
Scans one DOI/PMID per line and returns only the key retraction fields for each entry.
Find superseding work
retraction-checker-pp-cli superseded 10.1016/j.micpro.2020.103768 --json
Lists more-recent related papers ranked by citations, published after the retracted paper.
Throttle batch runs to avoid OpenAlex load-shedding
retraction-checker-pp-cli scan reading-list.txt --rate-limit 0.15 --agent
--rate-limit caps outbound requests per second across both Crossref and
OpenAlex (0, the default, disables the limiter). The default is off because a
single check is one request and needs no pacing — but scan over a large
bibliography and superseded both fan out into many back-to-back calls, and
OpenAlex rate-limits anonymous traffic: under load its public API sheds with
HTTP 503 "temporarily rate-limited due to heavy load" rather than queuing you.
When that happens a batch run degrades instead of completing.
Pass --rate-limit 0.15 (~9 requests/minute) for batched scan/superseded
runs to stay safely under the typical shared anonymous limit and let the whole
batch finish. Raise it if you have headroom; lower it if you still see 503s.
Pairing it with --mailto you@example.com (the Crossref/OpenAlex polite pool)
further improves your limits.
Watch a field
retraction-checker-pp-cli watch "crispr" --json
Baselines retraction notices for a topic and reports new ones on later runs.
Usage
Run retraction-checker-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data such as data.db |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
RETRACTION_CHECKER_CONFIG_DIR, RETRACTION_CHECKER_DATA_DIR, RETRACTION_CHECKER_STATE_DIR, or RETRACTION_CHECKER_CACHE_DIR
--home <dir> for this invocationRETRACTION_CHECKER_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export RETRACTION_CHECKER_HOME=/srv/retraction-checker
retraction-checker-pp-cli doctor
Under RETRACTION_CHECKER_HOME=/srv/retraction-checker, the four dirs resolve to /srv/retraction-checker/config, /srv/retraction-checker/data, /srv/retraction-checker/state, and /srv/retraction-checker/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"retraction-checker": {
"command": "retraction-checker-pp-mcp",
"env": {
"RETRACTION_CHECKER_HOME": "/srv/retraction-checker"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as RETRACTION_CHECKER_DATA_DIR overrides an explicit --home for that kind. Use RETRACTION_CHECKER_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting RETRACTION_CHECKER_HOME does not move files back to platform defaults, and doctor cannot find files left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. Run retraction-checker-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
works
Manage works
retraction-checker-pp-cli works get - Get a single work by DOIretraction-checker-pp-cli works search - Search or filter scholarly works
Output Formats
# Human-readable table (default in terminal, JSON when piped)
retraction-checker-pp-cli works get mock-value
# JSON for scripting and agents
retraction-checker-pp-cli works get mock-value --json
# Filter to specific fields
retraction-checker-pp-cli works get mock-value --json --select id,name,status
# Dry run — show the request without sending
retraction-checker-pp-cli works get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
retraction-checker-pp-cli works get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
retraction-checker-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run retraction-checker-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/retraction-checker-via-pp-cli/config.toml; --home, RETRACTION_CHECKER_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Rate-limited by Crossref — Pass --mailto you@example.com to join the polite pool for better limits
- OpenAlex 503 "temporarily rate-limited due to heavy load" (seen on
superseded and large scan runs) — OpenAlex sheds anonymous traffic under load. Re-run --rate-limit 0.15 (~9 req/min) to pace the batch below the shared anonymous limit; add --mailto you@example.com for the polite pool. See the "Throttle batch runs" recipe above.
- PMID not found — PMIDs are resolved to DOIs first; some records have no DOI and cannot be checked via Crossref