Journal Abbreviation Lookup

Look up journal/magazine name abbreviations using a multi-source cascade: JabRef database (~25K journals) → AbbrevISO API (ISO 4) → NLM Catalog (MEDLINE).

Critical rule: Always use jabbrv.py for lookups. Never guess abbreviations — even common journals have non-obvious abbreviations.

Quick Reference

Output format

Stdout is a stable JSON envelope when the CLI is not attached to a terminal

(piped or captured by an agent), and a human table/indented view when run on a

TTY. To force a format: --format json|table|human|auto. --json remains as a

back-compat alias for --format json. Flags may appear before or after the

subcommand.

Envelope shape (always the same fields for every subcommand):

• Success: { "ok": true, "data": ..., "meta": { "schema_version", "cli_version", "cache", "latency_ms" } }

• Partial success (batch): { "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }

• Error: { "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

Exit codes

Error codes (inside error.code )

Branch on error.code + error.retryable rather than exit code alone — exit

1 covers both upstream_unavailable and runtime_error. Full machine-readable

listing: python3 jabbrv.py schema → data.error_codes.

Environment variables (set by host, not by agent argv)

Trust boundary: these are read from the process environment, not from

arguments. The host or sandbox sets them; the agent cannot override them via

argv. Schema introspection: python3 jabbrv.py schema → data.global_env.

Retries, idempotency, and destructive intent

• **Branch on error.code + error.retryable**, not exit code alone. Exit 1

covers both upstream_unavailable (retry) and runtime_error (retry once,

then escalate).

• **bib --idempotency-key <token>** persists the success envelope next to

the output file as <output>.<token>.envelope.json. A retry with the same

key returns that envelope with meta.idempotent_replay: true instead of

rerunning the rewrite. Token must match [A-Za-z0-9._-]{1,64}.

• **cache rebuild** is atomic — downloads stage into a sibling directory

and the swap only happens if every file succeeded. If any fails, the

existing cache is preserved and the response is upstream_unavailable

(retryable). Add --yes to record meta.confirmed: true for audit

policies; the CLI itself never prompts, so --yes is not a gate.

Workflow

Step 1: Detect Intent

Step 2: Execute

Run the appropriate jabbrv.py command. The script handles:

• Local cache lookup (instant, ~25K journals from JabRef)

• AbbrevISO API fallback (algorithmic ISO 4 abbreviation, forward only)

• NLM Catalog fallback (biomedical journals, bidirectional)

First run downloads JabRef CSV cache files automatically (~2-5 MB).

Step 3: Present Results

• Show the full name, abbreviation, and source

• Note the standard (ISO 4 vs MEDLINE) when relevant

• For .bib processing: show the change summary before confirming

ISO 4 vs MEDLINE

Two common abbreviation standards exist:

JabRef provides ISO 4 style. NLM Catalog provides MEDLINE style. AbbrevISO computes ISO 4 algorithmically from LTWA (List of Title Word Abbreviations).

Common Abbreviation Patterns

Note: Single-word titles (e.g., "Nature", "Science", "Cell") are NOT abbreviated per ISO 4 rules.

Integration Examples

With Zotero

# Export BibTeX from Zotero, then standardize journal names

zot export COLLECTION_KEY --format bibtex > refs.bib

python3 jabbrv.py bib refs.bib

With LaTeX

# Before compiling, ensure all journal names are abbreviated

python3 jabbrv.py bib references.bib

# Use the output file (references_abbrev.bib) in your LaTeX document

Batch Processing

Create a text file with one journal name per line:

Nature Medicine

Journal of Biological Chemistry

Proceedings of the National Academy of Sciences

Then run:

python3 jabbrv.py batch journals.txt

Troubleshooting