Skip to content

mosaic get ​

Downloads the PDF of one paper by DOI, or of every DOI in a BibTeX or CSV file. Papers that fail can be retried in a browser: your Chrome, driven by mosaic (--auto), a window mosaic controls (--interactive), or your own browser, where you click (--handoff, --anna).

Usage ​

bash
mosaic get 10.3389/fphy.2019.00140                    # one paper
mosaic get --from refs.bib                            # every DOI in a BibTeX file
mosaic get --from refs.csv --oa-only                  # papers with no open copy count as skipped
mosaic get 10.1016/j.paerosci.2006.01.001 --auto      # your Chrome, unattended
mosaic get --from refs.bib --auto --max-auto 200      # the same over a list, past the 50-paper cap
mosaic get 10.1016/j.paerosci.2006.01.001 --handoff   # download it yourself; mosaic files it
mosaic get --from refs.bib --interactive              # retry failures in a visible browser
mosaic get 10.3389/fphy.2019.00140 --download-dir ~/papers/project

Behaviour ​

Where the PDF comes from, in order: a PDF already recorded for the paper in the cache; the paper's known PDF link; up to six open-access locations Unpaywall knows (needs mosaic config --unpaywall-email); a saved browser session (mosaic auth). Every file is checked to start with the PDF signature: an HTML page is never saved as a PDF. See downloads.

Metadata. Title, authors and year come from the cache, or from Crossref, so the file gets the same name a search would give it (filename_pattern, default {year}_{source}_{author}_{title}).

--from reads every doi = {...} field of a .bib file, or the doi column (any case) of a .csv file. Duplicates are downloaded once. One line per DOI, then a summary: downloaded, failed, skipped.

--interactive opens the failed papers in a browser window mosaic controls, with your saved sessions, where you log in or pass a check; it needs the browser extra. --handoff opens them one at a time in your default browser and watches the downloads folder (--watch-dir, or the detected one): the next PDF that appears is moved into the library under the paper's name. Press Enter when done with a paper, or to skip it. Hand-off works where publishers refuse any automated browser, as Elsevier does.

--auto drives your installed Chrome or Edge (on WSL the Windows one), with a dedicated mosaic profile, through each failed paper's PDF chain, and files the download. It runs unattended, one paper at a time: a paper behind a login the profile does not have is reported as "login needed" and skipped, and the run ends by naming those sites. Run from a terminal, it stops only for what needs you: a Cloudflare check to click, or the sign-in of your institutional proxy when its session has ended; Enter skips the paper in flight, q and Enter ends the run. With proxy.url set (mosaic config --proxy-url), every DOI starts at your institution's proxy instead of doi.org. At most 50 papers per run (--max-auto N). See the auto pass.

--anna is a hand-off to Anna's Archive: the failed papers open there, one at a time, in your own browser, and mosaic files what you download (mirror from config anna.mirror). See downloads.

Rescue order. Given together, the rescues run as --auto, then --interactive, then --handoff or --anna; each takes the papers the previous one left.

The failed papers. When papers stay without a PDF and the run has a terminal, mosaic asks whether to save their DOIs to <input>-failed.csv in the current directory (failed.csv for a single DOI), ready for a later mosaic get --from.

Exit code 1 if you give both a DOI and --from, neither, or a file that does not exist or has the wrong type; if the DOI has no downloadable copy; or, with --from, if any paper failed. Papers counted as skipped with --oa-only do not make it fail.

See also: tutorial 4, tutorial 5, downloading recipes, paywalls recipes.

Options ​

mosaic get [OPTIONS] [DOI]
ArgumentValueDescription
DOITEXTDOI of the paper to download (optional)
OptionValueDefaultDescription
--fromPATHBibTeX (.bib) or CSV (.csv) file containing DOIs to bulk-download
--oa-onlyTreat unresolvable papers as skipped rather than failed
--download-dirTEXTOverride PDF download directory for this run
--zoteroExport downloaded paper(s) to Zotero
--zotero-collectionTEXTZotero collection name (created if missing)
--zotero-localForce Zotero local API even when an API key is configured
--obsidianExport paper(s) as notes to an Obsidian vault
--obsidian-folderTEXTOverride Obsidian vault subfolder for this run
--interactive, -iRetry failed papers in a visible browser where you can log in or solve checks
--handoffOpen failed papers in your own browser and file the PDFs you download (works where publishers block automated browsers, e.g. Elsevier)
--annaOpen failed papers on Anna's Archive (/scidb/<DOI>) in your own browser and file the PDFs you download there; the mirror base comes from config anna.mirror (default https://annas-archive.gd)
--autoRetry failed papers with your own Chrome driven by mosaic over CDP (the Elsevier-included real-browser pass; needs Chrome/Edge installed)
--max-autoINTEGER RANGE50Papers --auto may attempt per run (it drives a real browser: keep it sane)
--watch-dirPATHBrowser download folder for --handoff (default: auto-detect)
--batchINTEGER RANGE1Papers --handoff opens at once; download them in any order

Released under GPL-3.0-or-later, BSD-2-Clause, BSD-3-Clause or MIT, at your choice.