astrobib

A terminal-based literature manager for astrophysics research

astrobib connects to the NASA/Harvard ADS to search, fetch, and organize papers as plain BibTeX files, with a fast terminal UI. It ships as a single native binary: instant startup, instant quit, no runtime dependencies.

Your library is just a directory of .bib files, indistinguishable from hand-written BibTeX, and cite keys derive from each paper's stable identity (arXiv ID or bibcode) — so any two copies of a paper, fetched by anyone at any time, agree on the key forever. Libraries from all earlier astrobib versions work unchanged.

Installation

uv tool install astrobib     # or: pipx install astrobib

Binary wheels cover macOS (arm64, x86_64) and Linux (x86_64, aarch64). Building from source needs a Rust toolchain: cargo install --git https://github.com/clemson-cal/astrobib.

Quick start

# set your ADS token (https://ui.adsabs.harvard.edu/user/settings/token)
export ADS_API_TOKEN=...

astrobib                     # launch the TUI
astrobib list                # CLI: newest papers
astrobib search '^andersson OR kw:"compact objects"'
astrobib add 2020ApJ...123..456Z
astrobib import refs.bib     # resolve a foreign .bib against ADS

The two-tier library model

astrobib always works on up to two libraries: a local bib directory (tier 2) and your global personal library (tier 1, at ~/.local/share/astrobib/library/). astrobib [LIBRARY_DIR] points tier 2 at any directory holding bib/; with no argument, the nearest ancestor of the current directory with a bib/ is used. A .tex or .md manuscript alongside activates citation tracking, but any bib directory works. With the global tier enabled (the default), reads merge both tiers and imports write to both — the paper repo stands alone for coauthors while your collection accrues. Press t (or click the global badge) to hide the global tier: reads and writes become purely local. Removing a local paper never destroys a sole copy — it is rescued into the global library. Both stores are plain bib/*.bib files, one paper per file, indistinguishable from hand-written BibTeX. Nothing else is ever written into your repos.

TUI overview

Scope capsules at the top switch between your library, saved ADS query tabs, and the manuscript view. Each keeps its own sort, and remembers it. An optional one-cell colour swatch column shows a metric — your own decaying priority, or ADS citation counts; switch it on from the table panel (|), like any other column. The pub card on the right shows the highlighted paper (hover the citekey column to preview others); an event log and clickable view badges sit at the bottom. Most things are clickable; every action has a key (? shows the cheat-sheet).

Keys

• / — live filter (query language below); S — new ADS query (↑/↓ sets the result count, ⌃r what ADS returns — both also clickable; pasting a DOI or ADS URL imports directly)
• j k g G — move; [ ] — switch scope (] past the last one composes a new query); ctrl+w — close query scope; r — refresh; + - — result count
• Space — select row (iOS-style selection mode); a — select visible; A — select all; Esc — done
• i — import ADS result(s); m — toggle manuscript/local membership; ⌫ — remove (with confirmation)
• p — download PDFs (ADS open-access, then arXiv); B — browser download (watches ~/Downloads); o — open PDF; X — clear PDF; double-click a row — open its PDF
• y — copy chord: yy cite key, yY full key, yb bibcode, ya/yx/yd ADS/arXiv/DOI URL, yp PDF path, yt title, yA abstract; card title/abstract/key are click-to-copy
• y q — copy the active query's whole configuration: its text, its result count and what ADS returns, as an ADS search URL. P — open the query configuration on the clipboard (it says so if the clipboard holds something else). Both round-trip, so a query pasted to a colleague arrives as the query you sent
• In any prompt: ⌃k / ⌃u / ⌃w kill to end of line, to start of line, and the previous word, and ⌃y yanks the last of them back; ⌥w copies what you are composing (from a query, the same URL as y q)
• E — edit the active query in place (text, result count and what ADS returns); S always composes a new one
• N — name the active query (the capsule label; persists across edits to the query, empty restores the derived name)
• C / R — open a citations / references query for the shown paper; v — pub view (the raw .bib); e — export the selection to a .bib file
• M — pick the metric the swatch column shows (priority or citations, distinct colormaps; show the column itself from |); . — priority 1.0, 0 — clear, < > — scale it (decays weekly); the wheel over a swatch does the same for that row
• | — table panel: show/hide columns, ←/→ to resize, s to sort by any of them (shown or not); Tab swaps the arrow keys between the panel and the table, Esc hands them back
• t — show/hide the global tier; D — pub card; L — event log; ? — keys; @ — about; q — quit

The side panels, the pub card and the footer are separated from the table by a faint tint rather than by border lines, and the tint is chosen from your terminal's own background: darker than it on a light theme, lighter on a dark one. astrobib asks the terminal at startup (OSC 11) and falls back to dark for terminals that do not answer — set ASTROBIB_THEME=light or dark to decide it yourself.

Filtering the library

Press / to filter as you type. Whitespace-separated terms AND together; each term is a case-insensitive partial match. Bare terms match author, title, abstract, key, keywords, and year; field prefixes narrow:

author:cabrera         author anywhere in the list
^andersson             first-author papers (= author:^andersson)
title:magnetar         word in title
abs:"fast radio burst" phrase in abstract
kw:"compact objects"   keyword
year:2015-2020         ranges; year:2020- open-ended
is:ms                  local/manuscript members;  is:pdf  cached PDFs
pri:>0.5  cit:>100    metric comparisons (> < or bare for ≥); no metric never matches
-abs:neutrino          leading - negates (NOT works too)
^andersson OR ^baxter  uppercase OR separates alternatives; AND binds tighter

Long queries wrap across as many rows as they need rather than scrolling out of sight; the text stays one line, and ⏎ still runs it. A half-typed query never errors. With a filter active, S pre-fills the equivalent ADS query — filter locally, escalate in one keystroke.

Pressing / offers these four as a starting point; click one to load it into an empty filter.

^andersson year:2019-                 first author, open-ended years
abs:"fast radio burst"                phrase in the abstract
is:pdf pri:>0.5                       has a PDF, high priority
kw:"compact objects" -abs:neutrino    keyword, and a negation

ADS queries

S passes your query to the ADS API unmodified, so the full Solr language works (bibstem:ApJL, citations(...), boolean grouping, …). Each query becomes a scope capsule, persisted per library context in tabs.json. The pub card walks the citation graph directly: click "cited by N" (or the citations/references affordances) to open a citations(...) or references(...) scope for the shown paper.

Pressing S offers these four as a starting point; click one to load it into an empty prompt.

abs:"little red dot" -doctype:abstract    phrase, minus meeting abstracts
author:"^Andersson, K." year:2020-        first author, from a year on
bibstem:ApJL abs:"magnetar"               one journal
arxiv_class:astro-ph.HE                   an arXiv subject class

Samples never carry an absolute upper year: recency is the prompt's own control (⌃r), and a baked-in end year would silently exclude the newest work once it passed.

A saved query reads as a feed: ADS is asked for the newest records by entry date — when it indexed them — not by publication date, so r brings back what has appeared since you last looked rather than what was published most recently. The Entered column shows that date beside Year; the table panel picks which of the four selection sorts a query uses. That sort chooses which records come back, so ordering a feed by citations gives the most cited among the newest n, not the most cited overall.

Markdown manuscripts

Literature reviews and notes work as manuscripts too: any .md files beside bib/ are scanned for citations (main.md is the sole root when present; Obsidian ![[embeds]] pull in more files, like \input). Cite pandoc-style — bare @Andersson2021 or bracketed [@Andersson2021; @Baxter2019] — or with Obsidian wikilinks: [[Andersson2021]] counts as a citation when it resolves in the library, and stays an ordinary note link when it doesn't. An unresolved @cite shows as missing in the Manuscript view, same as LaTeX. astrobib refs renders the bibliography of everything cited into the manuscript — a sorted, linked reference list (authors, year, italic title, journal, ADS/arXiv/DOI links) kept between <!-- astrobib:references --> markers, appended as a ## References section the first time. Regenerate any time; your prose is never touched.

Building with make

The dependency graph of a paper is acyclic, and astrobib refs implements the middle of it:

main.pdf  <-  main.tex, refs.bib
bib/      <-  main.tex          (citing a paper pulls it out of your library)
refs.bib  <-  main.tex, bib/

astrobib refs — copy newly cited papers into bib/, then write refs.bib from what is there. It stamps refs.bib's mtime even when the content is unchanged, so a make rule settles instead of re-running every build; no touch $@ is needed. astrobib refs --check — verify only: writes nothing, exits nonzero if refs.bib is stale or a cited paper is still missing from bib/. For CI and pre-commit hooks. astrobib refs --no-sync — write refs.bib from what bib/ already holds and fetch nothing, for a CI job that must not modify tracked files.

A complete Makefile is in docs/examples/Makefile.

refs.bib and co-authors

For TeX manuscripts, refs.bib regenerates silently whenever the TUI rescans — and the TUI rescans itself when you edit sources externally (mtimes are polled, like the original app): every cited manuscript-db member, emitted under the string you actually cited (full key or unambiguous prefix), so hash suffixes never need to appear in your .tex. astrobib refs [--prune] does the same from the CLI, first copying cited-but-missing entries into the manuscript db (--prune also removes uncited ones, rescuing sole copies). Co-authors don't need astrobib. They add a reference by pasting BibTeX from the ADS website into bib/any-name.bib (and, if they like, appending it to refs.bib by hand so the paper still compiles). Next time you check out the repo, astrobib tidy canonicalizes those files — re-keys them through ADS when needed, renames them to {Key}.bib, dedupes, rewrites the old keys inside your sources — and regenerates refs.bib for the commit. Migrating a manuscript that predates astrobib works the same way: in a directory with sources and its own loose .bib files but no bib/, astrobib tidy adopts it wholesale — builds bib/, resolves everything against ADS, rewrites your \cite keys in place, and regenerates refs.bib.

CLI

list, search [--ads], add <bibcode|ADS URL>, show <key>, rm <key> [--local-only] (sole copies rescued), import <file.bib> [--global-only|--local-only], refs [FILE] [--prune|--no-sync|--check] [--dry-run], tidy [--dry-run], convert bibcode|full|short (uniform cite keys, rewritten in your sources), update [--all] (arXiv → published refresh, same key forever), config [ads_token|email <value>] (show or set the environment), gc (report what the machine-local caches cost), plus --library PATH (relocate the global tier) and --no-global. import resolves each entry against ADS (arXiv ID → DOI → exact title+author+year) unless its cite key is already reproducible from its own data — canonical astrobib entries import byte-identically — and prints copy-pasteable key replacements for your .tex files.

See docs/DESIGN.md for the data-format contract. Bugs and feature requests: github.com/clemson-cal/astrobib/issues.

© 2026 Jonathan Zrake · MIT license · Clemson University Physics and Astronomy · Supported by NSF award number 2408034 Development assisted by Claude (Fable 5).