# bibtui

> A quiet, powerful home for your references.

[![PyPI](https://img.shields.io/pypi/v/bibtui)](https://pypi.org/project/bibtui/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Publish](https://github.com/tgoelles/bib_tui/actions/workflows/publish.yml/badge.svg)](https://github.com/tgoelles/bib_tui/actions/workflows/publish.yml)
[![CI](https://github.com/tgoelles/bib_tui/actions/workflows/ci.yml/badge.svg)](https://github.com/tgoelles/bib_tui/actions/workflows/ci.yml)

## Quick start

```bash
# Run without installing
uvx --prerelease=allow bibtui myrefs.bib

# Or install permanently
uv tool install --prerelease=allow bibtui
```

> **Why `--prerelease=allow`?** bibtui depends on `bibtexparser` v2, which is
> still in beta on PyPI. This flag tells uv to use it. Once bibtexparser
> publishes a stable v2 release this flag will no longer be needed.

---

## Screenshots

<!-- screenshots -->

| Light theme                            | Dark — Catppuccin Mocha                    |
| -------------------------------------- | ------------------------------------------- |
| ![light theme](docs/pictures/theme1.png) | ![catppuccin mocha](docs/pictures/theme2.png) |

| Nord — keywords modal                              |  |
| --------------------------------------------------- | - |
| ![nord with keywords modal](docs/pictures/theme3.png) |  |

<!-- recording -->

<!-- ![demo](docs/demo.gif) -->

---

**bibtui** is a beautiful, keyboard-driven terminal app for researchers who live
in the terminal. Browse and edit your `.bib` file, fetch open-access PDFs with a
single keystroke, track what you've read, and never leave the command line —
no database, no sync daemon, no account required.

> **Mouse users welcome.** bibtui works fully with the mouse — click, scroll, select.
> You just need to launch it from a terminal: `uvx --prerelease=allow bibtui myrefs.bib`

---

## Why bibtui?

|                                    | bibtui | JabRef | Zotero |
| ---------------------------------- | ------ | ------ | ------ |
| Runs in the terminal               | ✅     | ❌     | ❌     |
| No database / sync daemon          | ✅     | ✅     | ❌     |
| Git-friendly plain `.bib`        | ✅     | ✅     | ❌     |
| Works over SSH                     | ✅     | ❌     | ❌     |
| Full Textual theming               | ✅     | ❌     | ❌     |
| Pure Python, installs less than 1s | ✅     | ❌     | ❌     |

Well, I mostly built this for myself. I was trying many bibliography tools over the years and in the end stuck with JabRef. It worked directly on the bib file, had import from DOI, PDF fetching, ratings and PDF linking. What I did not like was the UI and the many features I don't need. Anyway, I kept using it, more or less frustrated.

Then I switched to Linux on my MacBook M1 and suddenly couldn't install JabRef anymore, even after trying different approaches. That was it, I decided to make my own that does what I want, looks nice, and nothing more.

I also wanted to try out Claude Code for a project from scratch, so yes, most of the code was AI-generated. Otherwise I would never have done it. It still took many hours of work and I used my experience from many Python projects. I reviewed everything and have tests for the non ui part.

---

## Features

- **Browse & search** — instant search across title, author, keywords, journals and cite key
- **Import by DOI** — paste a DOI and metadata is fetched automatically
- **Fetch PDFs automatically** — tries arXiv → Unpaywall (free, open-access) → direct URL
- **Library-wide actions** — fetch all missing PDFs and unify citekeys to AuthorYear
- **Add existing PDFs** — pick a file from your Downloads folder with a live filter
- **Edit entries** — field-by-field form *or* raw BibTeX editor (toggle with `v`)
- **Read states & priorities** — track what you've read and what matters most
- **Star ratings** — rate entries 1–5
- **Keywords editor** — manage tags inline
- **JabRef-compatible** — file links use JabRef conventions; open the same `.bib` in both tools
- **Git-friendly** — it's a plain text file (.bib); commit, diff, and collaborate normally
- **Full Textual theme support** — including automatic detection of the [omarchy](https://omarchy.org) themes
- **Works anywhere `uv` does** — SSH, HPC clusters, a colleague's laptop

---

## Installation

### Recommended — uv (fastest)

```bash
uv tool install --prerelease=allow bibtui
```
updating an exising installation:

```bash
uv tool upgrade bibtui
```

### pip

```bash
pip install --pre bibtui
```

### Try without installing

```bash
uvx --prerelease=allow bibtui references.bib
```

> **Note:** The `--prerelease=allow` / `--pre` flag is needed because bibtui depends on
> `bibtexparser` v2, which is currently in beta on PyPI. Once it releases a stable v2
> this flag will no longer be required.

---

## Usage

```
bibtui MyCollection.bib
```

On first launch bibtui shows a short onboarding wizard that pre-fills sensible
defaults for your PDF directory, Downloads folder, and Unpaywall email
(no registration required — the email is only used for rate-limiting).

---

## PDF workflow

`f` tries three sources in order:

1. **arXiv** — for entries with a `10.48550/arXiv.*` DOI or an `arxiv.org` URL
2. **Unpaywall** — free open-access lookup by DOI (set your email in Settings; no account needed)
3. **Direct URL** — if the entry's `url` field points directly to a PDF

PDFs are saved to your configured base directory and the entry's `file` field is
updated automatically in JabRef format.

---

## Philosophy

- Your `.bib` file is the source of truth
- No hidden database
- No setup, point and shoot possible
- No lock-in
- No accounts
- keyboard and mouse support
- nice looking
- focused featurset. For cleanup use [bibtex-tidy](https://github.com/FlamingTempura/bibtex-tidy) or work directly on the bib file

## Development

```bash
git clone https://github.com/tgoelles/bib_tui
cd bib_tui
uv sync
uv run bibtui tests/bib_examples/MyCollection.bib
```

Run the tests:

```bash
uv run pytest -m "not network"
```

Live-reload during development:

```bash
uv run textual run --dev src/bibtui/main.py -- tests/bib_examples/MyCollection.bib
```

---

## Related tools

- [JabRef](https://www.jabref.org/) — GUI reference manager, same `.bib` format
- [cobib](https://github.com/mrossinek/cobib) — another terminal BibTeX manager
- [bibman](https://codeberg.org/KMIJPH/bibman) — minimal TUI reference manager
- [bibiman](https://codeberg.org/lukeflo/bibiman) - looks interesting but it did not work

---

## FAQ

**Does this modify my `.bib` formatting?**
Yes. but we also write a backup file

**Can I use it alongside JabRef or XYZ tool for .bib?**
Yes. they both just read bib files and bibtui follows JabRef conventions.

## License

MIT © Thomas Gölles


