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

User wants...	Command
Abbreviate a journal name	`python3 jabbrv.py abbrev "Nature Medicine"`
Expand an abbreviation	`python3 jabbrv.py expand "Nat. Med."`
Auto-detect direction	`python3 jabbrv.py lookup "J. Am. Chem. Soc."`
Fuzzy search (paginated)	`python3 jabbrv.py search "biolog chem" --limit 10 --offset 0`
Process a .bib file	`python3 jabbrv.py bib refs.bib`
Preview .bib changes (no write)	`python3 jabbrv.py bib refs.bib --dry-run`
Explicit .bib output path	`python3 jabbrv.py bib refs.bib --output out.bib`
Expand .bib abbreviations	`python3 jabbrv.py bib refs.bib --expand`
Replay-safe .bib (retry returns cached envelope)	`python3 jabbrv.py bib refs.bib --idempotency-key run-001`
Batch text list	`python3 jabbrv.py batch journals.txt`
Batch as NDJSON stream	`python3 jabbrv.py batch journals.txt --stream`
Inspect cache state	`python3 jabbrv.py cache status`
Download missing cache files	`python3 jabbrv.py cache update`
Preview what update would fetch	`python3 jabbrv.py cache update --dry-run`
Atomic rebuild (destructive, with audit marker)	`python3 jabbrv.py cache rebuild --yes`
Preview rebuild (no delete)	`python3 jabbrv.py cache rebuild --dry-run`
Suppress stderr progress	`python3 jabbrv.py --quiet cache update`
Machine-readable CLI contract	`python3 jabbrv.py schema`
Schema for one subcommand	`python3 jabbrv.py schema lookup`

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

Code	Meaning
`0`	success (including partial success)
`1`	runtime / upstream error
`2`	validation / bad input (missing file, bad flag)
`3`	not found (the looked-up journal does not exist)

Error codes (inside

error.code

)

Code	Retryable	Exit	Meaning
`not_found`	no	3	Lookup completed but no source matched
`upstream_unavailable`	yes	1	One or more upstream APIs failed transiently; the lookup could not be concluded. Carries `error.sources[]` listing each failure. Retry later.
`file_not_found`	no	2	Input file path does not exist
`validation_error`	no	2	Bad argument or flag combination
`runtime_error`	yes	1	Unexpected internal error

Branch on

error.code

error.retryable

rather than exit code alone — exit

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)

Variable	Effect
`JABBRV_CACHE_DIR`	Override the cache directory (default: `<install>/cache` ). Useful in sandboxes where the install tree is read-only.
`JABBRV_OFFLINE`	Truthy ( `1` / `true` / `yes` / `on` ) skips AbbrevISO and NLM; only the local JabRef cache is consulted. Misses become definitive `not_found` (not retryable) since the host has declared upstream off-limits. `meta.offline: true` appears in every envelope so callers can see the policy.
`NO_COLOR`	https://no-color.org convention. Any non-empty value disables color. No ANSI is emitted today; `meta.no_color: true` appears when set so callers can see the policy.

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

Intent	Action
Single journal name/abbreviation	Use `lookup` (auto-detect) or `abbrev` / `expand` (explicit direction)
"What's the abbreviation for X?"	Use `abbrev`
"What journal is X?"	Use `expand`
Partial or uncertain name	Use `search` for fuzzy matching
Fix journal names in .bib file	Use `bib`
List of journals to process	Use `batch`

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:

Standard	Periods	Example	Used by
ISO 4	Yes	Nat. Med.	Most publishers, BibTeX
MEDLINE	No	Nat Med	PubMed, NLM databases

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

Word	Abbreviation	Word	Abbreviation
Journal	J.	International	Int.
American	Am.	European	Eur.
Science/Sciences	Sci.	Medicine/Medical	Med.
Biology/Biological	Biol.	Chemistry/Chemical	Chem.
Physics/Physical	Phys.	Engineering	Eng.
Research	Res.	Review/Reviews	Rev.
Society	Soc.	National	Natl.
Proceedings	Proc.	Transactions	Trans.
Letters	Lett.	Communications	Commun.
Applied	Appl.	Computational	Comput.

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

Integration Examples

With Zotero

bash

# Export BibTeX from Zotero, then standardize journal names
zot export COLLECTION_KEY --format bibtex > refs.bib
python3 jabbrv.py bib refs.bib

With LaTeX

bash

# 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:

bash

python3 jabbrv.py batch journals.txt

Troubleshooting

Issue	Solution
"No result found"	Try `search` with partial name for fuzzy matching
Cache download fails	Check network connection, retry with `cache update` (or `cache rebuild` to force)
Wrong abbreviation style	JabRef = ISO 4 (with dots), NLM = MEDLINE (no dots)
BibTeX field not detected	Ensure format is `journal = {Name}` (curly braces)

journal-abbrev

NPX Install

Tags

SKILL.md Content

Journal Abbreviation Lookup

Quick Reference

Output format

Exit codes

Error codes (inside
`error.code`
)

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

Retries, idempotency, and destructive intent

Workflow

Step 1: Detect Intent

Step 2: Execute

Step 3: Present Results

ISO 4 vs MEDLINE

Common Abbreviation Patterns

Integration Examples

With Zotero

With LaTeX

Batch Processing

Troubleshooting

journal-abbrev

NPX Install

Tags

SKILL.md Content

Journal Abbreviation Lookup

Quick Reference

Output format

Exit codes

Error codes (inside error.code)

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

Retries, idempotency, and destructive intent

Workflow

Step 1: Detect Intent

Step 2: Execute

Step 3: Present Results

ISO 4 vs MEDLINE

Common Abbreviation Patterns

Integration Examples

With Zotero

With LaTeX

Batch Processing

Troubleshooting

Error codes (inside
`error.code`
)