pynakes

pynakes is a reference management engine for BibTeX and BibLaTeX bibliographies and their research materials, exposed through a Python library and CLI.

Acquire and curate references, compare and enrich records, organize groups, track citations in manuscripts, and optionally manage PDFs and source bundles through Pinax, addressed by citation key. The .bib remains authoritative, and JabRef interoperability keeps existing libraries usable across tools.

Status: the engine is Beta. Its CLI, JSON envelope, and error codes follow the compatibility policy; the Python API is experimental until 1.0. The VS Code editor is an unpublished Alpha.

What it offers

• Source preservation. Untouched entries write back byte-for-byte. Surgical edits keep diffs focused; whole-file formatting is an explicit operation.
• Review before writing. Preview changes with --dry-run --diff. Writes are atomic and re-parse-validated, backups are optional, and ambiguous operations report conflicts rather than guessing.
• Reference management. Import, search, lint, normalize, deduplicate, edit, convert, and export references. Track TeX citations and prepare scrubbed public copies without altering the working bibliography.
• References and materials together. Pinax tracks PDFs, source bundles, and provenance. Materials can follow entries through citation-key changes and bibliography combine/split operations.
• Research reads. Compare a set of papers through bounded, paged reads of their abstracts, materials, and recorded provenance; save selections as named queries; describe a bibliography's coverage with analyze; and map its co-author network with coauthors.
• Automation. Structured JSON, change plans, exit codes, and machine-readable capabilities support scripts, CI, and agent workflows. Network access is explicit.

Install

Requires Python 3.12+ on Linux, macOS, or Windows. Install the published release with:

pip install pynakes

Or install the CLI as an isolated tool with uv:

uv tool install pynakes

For this development checkout and optional tooling, see the installation guide.

Quick start

This offline example creates a bibliography and previews an edit before applying it:

pynakes init refs.bib
pynakes ref add refs.bib Newton1687 --type book --field author="Isaac Newton" --field title="Principia" --field year=1687 --field publisher="Royal Society"
pynakes inspect refs.bib --json
pynakes ref edit refs.bib Newton1687 --field note="Reviewed" --dry-run --diff
# Apply after reviewing the diff:
pynakes ref edit refs.bib Newton1687 --field note="Reviewed"
pynakes search refs.bib Principia --json

When the current directory has exactly one .bib file, commands that take one bibliography can infer its path. Otherwise, provide the file explicitly. See the quick-start guide for imports, normalization, and other workflows.

The Python library uses the same staged lifecycle:

from pynakes import Bibliography, CanonicalLayout

bib = Bibliography.open("refs.bib")
bib.format(CanonicalLayout(field_order="preferred", wrap_values="stable"))
print(bib.diff())
# Commit after reviewing the diff:
bib.commit(backup=True)

See the API reference for preview(), change_plan(), and the other Bibliography operations.

VS Code editor

The editor companion provides a bibliography table, entry and metadata editing, groups, citation navigation, and material access using the same engine. It is a project-scoped editor, currently an unpublished alpha. Its user guide and build instructions are maintained separately.

Documentation

• Usage and commands
• Pinax: references and their materials
• Metadata settings
• JabRef compatibility
• Network and privacy
• Automation and JSON contract
• Git workflows and CI
• Architecture

The planned Library and rebuildable Catalogue APIs extend this engine to collection-wide work; they are not implemented yet. See the vision and development plan. Release history is in the changelog.

Contributing and license

See CONTRIBUTING.md for development setup and checks. Licensed under MIT.

Named after the Pinakes, Callimachus’s catalogue of the Library of Alexandria. A .bib is the index card; a pinax is the card together with the shelf it points at.