### Install bibaudit with uv Source: https://lorenzofabbri.github.io/bibaudit Installs bibaudit as a standalone tool using uv. Requires uv to be installed. ```bash uv tool install bibaudit ``` -------------------------------- ### Install bibaudit with pip Source: https://lorenzofabbri.github.io/bibaudit Alternative installation method using pip. ```bash pip install bibaudit ``` -------------------------------- ### Run bibaudit from a checkout Source: https://lorenzofabbri.github.io/bibaudit Installs dependencies and runs bibaudit from a checkout of the repository. ```bash uv sync && uv run bibaudit --help ``` -------------------------------- ### Example output of bibaudit check --suggest Source: https://lorenzofabbri.github.io/bibaudit/suggest Shows the announcement on standard error when suggestions are written. The line indicates the number of entries and fields, and that the original file was not modified. ```bash $ bibaudit check references.bib --suggest bibaudit: references.suggested.bib (1 entries, 5 fields) — review before use; references.bib was not modified ``` -------------------------------- ### GitHub Actions workflow for bibaudit checks Source: https://lorenzofabbri.github.io/bibaudit/ci GitHub Actions workflow that installs bibaudit via uv, restores a cache, runs a bibliography check with a polite User-Agent, and produces a JSON report. The second check uses --offline to avoid network access, and if: always() with continue-on-error: true ensures the artifact is uploaded even when the first check fails. ```yaml name: references on: [push, pull_request] jobs: bibaudit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: astral-sh/setup-uv@v10.1.0 - run: uv tool install bibaudit - run: echo "$HOME/.local/bin" >> "$GITHUB_PATH" - name: Restore the registry cache uses: actions/cache@v6 with: path: .bibaudit-cache key: bibaudit-${{ hashFiles('references.bib') }} restore-keys: bibaudit- - name: Check the bibliography run: > bibaudit check references.bib --cache-dir .bibaudit-cache --mailto ${{ secrets.CONTACT_EMAIL }} - name: Machine-readable report if: always() continue-on-error: true run: > bibaudit check references.bib --offline --cache-dir .bibaudit-cache --format json --output audit.json - uses: actions/upload-artifact@v4 if: always() with: name: bibaudit-report path: audit.json ``` -------------------------------- ### Run bibaudit check on various inputs Source: https://lorenzofabbri.github.io/bibaudit/cli Shows four example invocations of the `check` subcommand: auditing a bibliography file, auditing markdown documents with an explicit bibliography, auditing a Zotero SQLite library, and auditing the current directory with JSON output written to a file. The `check` subcommand accepts one or more paths that can be bibliographies, documents, Zotero libraries, or directories. ```bash bibaudit check references.bib bibaudit check notes/**/*.md --bibliography library.bib bibaudit check ~/Zotero/zotero.sqlite bibaudit check . --format json --output audit.json ``` -------------------------------- ### Adjudicate differences in .bibaudit.toml Source: https://lorenzofabbri.github.io/bibaudit/suppressions Example of a `.bibaudit.toml` suppression file. Each `[[ignore]]` table must include a `reason`; only `key`, `field`, `kind`, and `reason` are allowed. Unknown keys are refused by name, and `field` defaults to `"*"` if misspelled, which would silence all differences on that entry. ```toml [[ignore]] key = "papantoniou2017colorectal" field = "authors" reason = "Crossref returns mojibake surnames; checked against the PDF 2026-07-30" [[ignore]] key = "*" field = "publisher" reason = "publisher names churn with imprint mergers; not tracked here" ``` -------------------------------- ### Suggested BibTeX entry with filled fields Source: https://lorenzofabbri.github.io/bibaudit/suggest Example of a suggested entry where missing fields (journal, volume, number, pages, publisher) are filled from a Crossref record. The original title, author, and year are preserved. ```bibtex @article{smith2020, title = {A study of things}, author = {Smith, John}, year = {2020}, journal = {Journal of Testing}, volume = {5}, number = {2}, pages = {100-110}, publisher = {Test Publisher}, } ``` -------------------------------- ### Inspect and clear the bibaudit cache Source: https://lorenzofabbri.github.io/bibaudit/cli Use these commands to inspect or empty the bibaudit cache. `info` prints the cache directory, the number of stored responses, and their total size; `clear` empties it. Both accept `--cache-dir`, which must match the one given to `check`. If the directory cannot be created, both report the failure on stderr rather than showing a working, empty cache. ```bash bibaudit cache info bibaudit cache clear ``` -------------------------------- ### Run bibaudit check with --suggest Source: https://lorenzofabbri.github.io/bibaudit/suggest Command to generate suggested fixes for a .bib file. Writes references.suggested.bib and references.suggested.diff beside the original, never modifying it. Output goes to standard error. ```bash bibaudit check references.bib --suggest ``` -------------------------------- ### Check a bibliography file Source: https://lorenzofabbri.github.io/bibaudit Checks a bibliography file. The command outputs per-reference verdicts and a final PASS/FAIL line. ```bash bibaudit check references.bib ``` -------------------------------- ### Show cache directory with bibaudit cache info Source: https://lorenzofabbri.github.io/bibaudit/colophon Prints the directory where bibaudit stores cached Crossref responses. Records are named by SHA-256 of the lookup key and sharded into two-character subdirectories. The --cache-ttl option (default 90 days) controls reuse, not readability; files are never expired from disk. ```bash bibaudit cache info ``` -------------------------------- ### Run bibaudit check on references.bib Source: https://lorenzofabbri.github.io/bibaudit Run bibaudit check on references.bib. The output shows three references checked, with one BAD-ID (unresolved DOI), one FIELD-MISMATCH (year mismatch), and one INCOMPLETE entry that appears only in the summary. The run exits 1; exit 2 means the tool could not run at all. ```text $ bibaudit check references.bib bibaudit — 3 references checked BAD-ID (1) the identifier resolves in no consulted registry jones2020method references.bib:23 doi/unresolved (resolves in no consulted registry) stored 10.1016/j.jclinepi.2020.99999 registry FIELD-MISMATCH (1) right work, but stored metadata disagrees with the registry beral2003breast references.bib:11 year/mismatch stored 2004 crossref issued=2003, print=2003, pubmed:issued=2003 summary BAD-ID 1 FIELD-MISMATCH 1 INCOMPLETE 1 errors by field year=1, doi=1 suppressed 1 (1 registry defect(s)) (--show-suppressed to list) FAIL — 2 reference(s) in the failing set bibaudit verifies that each reference exists and that its stored metadata matches the publisher's record. It does not and cannot verify that a cited work supports the statement it is attached to — that requires reading the paper. ``` -------------------------------- ### Generated file header for bibaudit check --suggest Source: https://lorenzofabbri.github.io/bibaudit/suggest The header that `bibaudit check --suggest` writes at the top of the generated `.suggested.bib` file. It explains that the file is a proposed copy of references.bib, that values were added only where fields were absent or a DOI was proposed, and that no existing values were changed. It also notes that bibaudit never writes to references.bib itself and that the header appears first in the `.diff` file. ```text % --------------------------------------------------------------------- % GENERATED by `bibaudit check --suggest`. Review before use. % % This is a proposed copy of references.bib. A value was added here only where % (a) the field was completely absent from the original entry and a % consulted registry supplied one, or % (b) a DOI was proposed for an entry that had none, confirmed by title, % author and year corroboration. % No existing value in references.bib was ever changed, removed, or judged against % another. See references.suggested.diff for the exact, minimal set of lines added. % % Registries the proposed values in this file came from: crossref % % bibaudit never writes to references.bib itself. Verify each proposed value % against the registry before applying any of it by hand. % --------------------------------------------------------------------- ``` -------------------------------- ### compare.CHECKED_FIELDS list Source: https://lorenzofabbri.github.io/bibaudit/why The complete list of stored fields compared against the registry. Fields outside this tuple are never adjudicated; the DOI and the entry's own type are inspected but cannot produce a mismatch. ```text title, authors, year, container, volume, issue, pages, publisher, pmid ``` -------------------------------- ### Make target for bibaudit check Source: https://lorenzofabbri.github.io/bibaudit/ci Defines a make target that runs bibaudit check on references.bib and sources/. The target fails when bibaudit exits with code 1 or 2, and works identically under any runner because make propagates the exit code. ```makefile verify-refs: bibaudit check references.bib sources/ ``` -------------------------------- ### bibaudit check --show-suppressed output Source: https://lorenzofabbri.github.io/bibaudit/suppressions Run bibaudit check with --show-suppressed to list adjudicated differences. The output shows the ADJUDICATED entry, the suppressed difference with stored and crossref values, and the summary line that splits suppressed into registry defects and adjudications. Without the flag, the entry is not printed but the count remains. ```bash $ bibaudit check references.bib --show-suppressed bibaudit — 1 references checked ADJUDICATED (1) a difference this project's .bibaudit.toml decided to accept papantoniou2017colorectal references.bib:41 ~ volume/suppressed:mismatch (Crossref has the wrong volume; checked against the PDF 2026-07-30) ~ stored 186 ~ crossref 185 summary ADJUDICATED 1 suppressed 1 (1 adjudicated here) PASS — no reference in the failing set bibaudit verifies that each reference exists and that its stored metadata matches the publisher's record. It does not and cannot verify that a cited work supports the statement it is attached to — that requires reading the paper. ``` -------------------------------- ### Set --fail-on to custom verdicts or empty Source: https://lorenzofabbri.github.io/bibaudit/verdicts Use --fail-on to override the default failing set (RETRACTED,BAD-ID,WRONG-WORK,FIELD-MISMATCH,UNCONFIRMED). The empty string makes no verdict fail the run. ```bash bibaudit check references.bib --fail-on RETRACTED,BAD-ID,WRONG-WORK bibaudit check references.bib --fail-on '' # no verdict fails the run ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.