CLI Reference

Complete command-line interface documentation.

Main Command

linkml-reference-validator [OPTIONS] COMMAND [ARGS]...

Options

• --help - Show help message and exit

Commands

• lookup - Look up reference metadata (quick lookups)
• validate - Validate supporting text against references
• repair - Repair supporting text validation errors
• cache - Manage reference cache

---

lookup

Look up reference metadata and content. Useful for quick "what is this PMID?" lookups.

Usage

linkml-reference-validator lookup [OPTIONS] REFERENCE_ID [REFERENCE_ID...]

Arguments

• REFERENCE_ID (required) - One or more reference IDs (e.g., PMID:12345678, DOI:10.1234/example)

Options

• --format, -f [md|json|yaml|text] - Output format (default: md)
• --no-cache - Bypass disk cache and fetch fresh from source
• --download-files, -D - Download supplementary files from repositories (e.g., Zenodo)
• --cache-dir PATH, -c PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Basic lookup:

linkml-reference-validator lookup PMID:16888623

Multiple references:

linkml-reference-validator lookup PMID:16888623 PMID:33505029

JSON output:

linkml-reference-validator lookup PMID:16888623 --format json

YAML output:

linkml-reference-validator lookup PMID:16888623 --format yaml

Text output (human-readable):

linkml-reference-validator lookup PMID:16888623 --format text

Force fresh fetch (bypass cache):

linkml-reference-validator lookup PMID:16888623 --no-cache

Zenodo DOI with supplementary files:

linkml-reference-validator lookup DOI:10.5281/zenodo.7961621

Download supplementary files:

linkml-reference-validator lookup -D DOI:10.5281/zenodo.7961621

Output Format

Markdown (default):

---
reference_id: PMID:16888623
title: MUC1 oncoprotein blocks nuclear targeting...
authors:
- Raina D
- Ahmad R
journal: Cancer Research
year: '2006'
doi: 10.1158/0008-5472.CAN-06-0205
keywords:
- Adaptor Proteins, Signal Transducing/metabolism
- Cell Line, Tumor
content_type: abstract_only
---

# MUC1 oncoprotein blocks nuclear targeting...
**Authors:** Raina D, Ahmad R, ...
**Journal:** Cancer Research (2006)
**DOI:** [10.1158/...](https://doi.org/10.1158/...)

## Content

1. Cancer Res. 2006 Jul 1;66(13):6715-21...

Text format:

Reference: PMID:16888623
Title: MUC1 oncoprotein blocks nuclear targeting...
Authors: Raina D, Ahmad R, ...
Journal: Cancer Research (2006)
DOI: 10.1158/0008-5472.CAN-06-0205
Keywords: Adaptor Proteins, Signal Transducing/metabolism, Cell Line, Tumor, ...
Content type: abstract_only

--- Content ---
1. Cancer Res. 2006 Jul 1;66(13):6715-21...

With supplementary files (Zenodo):

Reference: DOI:10.5281/zenodo.7961621
Title: Gene Ontology Curators AI Workshop
Authors: Dickinson R, Carbon S, Mungall CJ
...
Content type: abstract_only

--- Supplementary Files (3) ---
  - Dickinson_Varenna2022.pdf (1,975,995 bytes)
  - workshop_slides.pptx (2,345,678 bytes)
  - data_analysis.xlsx (123,456 bytes)

--- Content ---
...

Exit Codes

• 0 - At least one reference fetched successfully
• 1 - All references failed to fetch

---

validate

Validate supporting text against references.

linkml-reference-validator validate COMMAND [ARGS]...

Subcommands

• text - Validate a single text quote
• text-file - Validate supporting text extracted from a text file via regex
• data - Validate supporting text in data files

---

validate text

Validate a single supporting text quote against a reference.

Usage

linkml-reference-validator validate text [OPTIONS] TEXT REFERENCE_ID

Arguments

• TEXT (required) - The supporting text to validate
• REFERENCE_ID (required) - Reference ID (e.g., PMID:12345678 or DOI:10.1234/example)

Options

• --title, -t TEXT - Expected title to validate against the reference title
• --cache-dir PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Basic validation:

linkml-reference-validator validate text \
  "MUC1 oncoprotein blocks nuclear targeting" \
  PMID:16888623

With custom cache directory:

linkml-reference-validator validate text \
  "MUC1 oncoprotein blocks nuclear targeting" \
  PMID:16888623 \
  --cache-dir /path/to/cache

With verbose output:

linkml-reference-validator validate text \
  "MUC1 oncoprotein blocks nuclear targeting" \
  PMID:16888623 \
  --verbose

With title check:

linkml-reference-validator validate text \
  "Airway epithelial brushings" \
  GEO:GSE67472 \
  --title "Airway epithelial gene expression in asthma versus healthy controls"

With editorial notes:

linkml-reference-validator validate text \
  'MUC1 [mucin 1] oncoprotein blocks nuclear targeting' \
  PMID:16888623

With ellipsis:

linkml-reference-validator validate text \
  "MUC1 oncoprotein ... nuclear targeting" \
  PMID:16888623

With DOI:

linkml-reference-validator validate text \
  "Nanometre-scale thermometry" \
  DOI:10.1038/nature12373

Exit Codes

• 0 - Validation successful
• 1 - Validation failed

Output Format

Validating text against PMID:16888623...
  Text: MUC1 oncoprotein blocks nuclear targeting

Result:
  Valid: True
  Message: Supporting text validated successfully in PMID:16888623
  Matched text: MUC1 oncoprotein blocks nuclear targeting...

---

validate text-file

Validate supporting text in a text file by extracting quotes and references with a regex.

Usage

linkml-reference-validator validate text-file [OPTIONS] FILE_PATH

Arguments

• FILE_PATH (required) - Path to a text file (e.g., OBO, plain text)

Options

• --regex, -r TEXT (required) - Regular expression with capture groups for text and reference ID
• --text-group, -t INTEGER - Capture group number for supporting text (default: 1)
• --ref-group, -R INTEGER - Capture group number for reference ID (default: 2)
• --summary, -s - Show only summary statistics (skip per-line output)
• --cache-dir PATH, -c PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Validate OBO axiom annotations:

linkml-reference-validator validate text-file my_ontology.obo \
  --regex 'ex:supporting_text="([^"]*)\[(\S+:\S+)\]"' \
  --text-group 1 \
  --ref-group 2

Summary only:

linkml-reference-validator validate text-file my_ontology.obo \
  --regex 'ex:supporting_text="([^"]*)\[(\S+:\S+)\]"' \
  --summary

Exit Codes

• 0 - Validation successful
• 1 - Validation failed

---

validate data

Validate supporting text in data files against their cited references.

Usage

linkml-reference-validator validate data [OPTIONS] DATA_FILE

Arguments

• DATA_FILE (required) - Path to data file (YAML/JSON)

Options

• --schema PATH, -s PATH (required) - Path to LinkML schema file
• --target-class TEXT, -t TEXT - Target class to validate (optional)
• --cache-dir PATH, -c PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Basic validation:

linkml-reference-validator validate data \
  data.yaml \
  --schema schema.yaml

With target class:

linkml-reference-validator validate data \
  data.yaml \
  --schema schema.yaml \
  --target-class Statement

With custom cache:

linkml-reference-validator validate data \
  data.yaml \
  --schema schema.yaml \
  --cache-dir /path/to/cache

With verbose output:

linkml-reference-validator validate data \
  data.yaml \
  --schema schema.yaml \
  --verbose

Exit Codes

• 0 - All validations passed
• 1 - One or more validations failed

Output Format

The summary separates work performed from issues found:

Validation Summary:
  Input files: 2
  Files validated: 2
  Snippets checked: 3
  Snippets skipped: 0
  Snippets unavailable: 0
  Titles checked: 1
  Issues found: 1
  Issues found in 1 file(s) (1 validation issue(s))
  Failing files:
    bad.yaml

• Input files counts supplied paths, including files that cannot be read.
• Files validated counts files with at least one mapping submitted to the validator. An empty mapping counts; an empty list has no instances and does not. A mixed list containing valid mappings and malformed entries counts once and still fails. Entry diagnostics use zero-based indexes.
• Snippets checked counts executed comparisons against reference content, including matches and mismatches. Multiple excerpt slots each count separately.
• Snippets skipped counts snippet/reference pairs bypassed by skip_prefixes.
• Snippets unavailable counts attempted snippet validations where the reference could not be fetched or had no content. These are not completed comparisons.
• Titles checked counts actual title comparisons, including those performed alongside snippets. Missing titles and skipped/unavailable references do not count.
• Issues found counts emitted validation issues. Blank excerpts may produce an issue without any comparison; file read/parse or data-format errors appear in the failing-file list without adding a fabricated validation issue.

Absent excerpts and excerpts without a usable reference perform no comparison. Counters come from execution and reset for each LinkML validation call; the CLI accumulates all instances and files. The public plugin exposes snippets_checked, snippets_skipped, snippets_unavailable, and titles_checked after validation. When using lazy process() or iter_results() APIs, exhaust the result iterator before reading final counters. Unconsumed or partially consumed iterators do not provide final counts; Validator.validate() consumes the iterator for you.

Title-only skips and unavailable titles have no separate summary counters: they leave all check counters at zero. A skipped title emits no issue; an unavailable standalone title emits an issue. Existing title behavior is preserved: a reference missing its title is an issue for standalone title validation, but a title supplied alongside an excerpt is not compared or reported when the reference has no title.

A zero-snippet run prints No snippet comparisons were performed. This includes empty input collections and title-only runs. Exit behavior is unchanged: no issues or file errors means exit 0, even when zero snippets were checked; issues or file errors mean exit 1. Failed file paths are listed at the end, including unreadable files, while later files continue to be processed.

---

repair

Repair supporting text validation errors.

linkml-reference-validator repair COMMAND [ARGS]...

Subcommands

• text - Repair a single text quote
• data - Repair supporting text in data files

---

repair text

Attempt to repair a single supporting text quote.

Usage

linkml-reference-validator repair text [OPTIONS] TEXT REFERENCE_ID

Arguments

• TEXT (required) - The supporting text to repair
• REFERENCE_ID (required) - Reference ID (e.g., PMID:12345678 or DOI:10.1234/example)

Options

• --cache-dir PATH, -c PATH - Directory for caching references
• --config PATH - Path to configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --auto-fix-threshold FLOAT, -a FLOAT - Minimum similarity for auto-fixes (default: 0.95)
• --help - Show help message

Examples

Repair character normalization:

linkml-reference-validator repair text \
  "CO2 levels were measured" \
  PMID:12345678

With verbose output:

linkml-reference-validator repair text \
  "protein functions in cells" \
  PMID:12345678 \
  --verbose

Exit Codes

• 0 - Repair successful or already valid
• 1 - Could not repair

Output Format

Successful repair:

Attempting repair for PMID:12345678...
  Text: CO2 levels were measured

Result:
  ✓ Repaired successfully
    Original: CO2 levels were measured
    Repaired: CO₂ levels were measured
    Action: CHARACTER_NORMALIZATION (Character normalization fix)
    Confidence: HIGH

Already valid:

Result:
  ✓ Text already valid - no repair needed

Could not repair:

Result:
  ✗ Could not repair: Flagged for removal - text not found in reference
    Suggestion: REMOVAL
    Confidence: VERY_LOW (12%)

---

repair data

Repair supporting text in data files.

Usage

linkml-reference-validator repair data [OPTIONS] DATA_FILE

Arguments

• DATA_FILE (required) - Path to data file (YAML)

Options

• --schema PATH, -s PATH (required) - Path to LinkML schema file
• --target-class TEXT, -t TEXT - Target class to validate
• --dry-run / --no-dry-run, -n / -N - Show changes without applying (default: dry-run)
• --auto-fix-threshold FLOAT, -a FLOAT - Minimum similarity for auto-fixes (default: 0.95)
• --output PATH, -o PATH - Output file path (default: overwrite with backup)
• --config PATH - Path to configuration file (.yaml)
• --cache-dir PATH, -c PATH - Directory for caching references
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Dry run (default):

linkml-reference-validator repair data \
  disease.yaml \
  --schema schema.yaml \
  --dry-run

Apply repairs:

linkml-reference-validator repair data \
  disease.yaml \
  --schema schema.yaml \
  --no-dry-run

Output to new file:

linkml-reference-validator repair data \
  disease.yaml \
  --schema schema.yaml \
  --no-dry-run \
  --output repaired.yaml

With configuration file:

linkml-reference-validator repair data \
  disease.yaml \
  --schema schema.yaml \
  --config .linkml-reference-validator.yaml

Custom threshold:

linkml-reference-validator repair data \
  disease.yaml \
  --schema schema.yaml \
  --auto-fix-threshold 0.98 \
  --no-dry-run

Exit Codes

• 0 - Repair completed (may have suggestions)
• 1 - Repair completed but has removals or unverifiable items

Output Format

[DRY RUN] Repairing disease.yaml
  Schema: schema.yaml
  Auto-fix threshold: 0.95
  Cache directory: references_cache

Found 5 evidence item(s) to process

============================================================
Repair Report
============================================================

HIGH CONFIDENCE FIXES (auto-applicable):
  PMID:12345678 at evidence[0].supporting_text:
    Character normalization fix
    'CO2 levels...' → 'CO₂ levels...'

SUGGESTED FIXES (review recommended):
  PMID:23456789 at evidence[1].supporting_text:
    Inserted ellipsis between non-contiguous parts

RECOMMENDED REMOVALS (low confidence):
  PMID:34567890 at evidence[2].supporting_text:
    Similarity: 8%
    Snippet: 'Fabricated text...'

------------------------------------------------------------
Summary:
  Total items: 5
  Already valid: 2
  Auto-fixes: 1
  Suggestions: 1
  Removals: 1
  Unverifiable: 0

---

Configuration File

Create .linkml-reference-validator.yaml for project-specific settings. Use the validation section for reference fetching behavior and repair for auto-fix settings.

validation:
  reference_prefix_map:
    geo: GEO
    NCBIGeo: GEO

  # Minimum non-whitespace characters an excerpt must quote.
  # 0 disables the check; empty excerpts are rejected regardless.
  min_excerpt_length: 0

repair:
  # Confidence thresholds
  auto_fix_threshold: 0.95
  suggest_threshold: 0.80
  removal_threshold: 0.50

  # Character mappings
  character_mappings:
    "+/-": "±"
    "CO2": "CO₂"
    "H2O": "H₂O"

  # References to skip
  skip_references:
    - "PMID:12345678"

  # References trusted despite low similarity
  trusted_low_similarity:
    - "PMID:98765432"

---

cache

Manage reference cache.

linkml-reference-validator cache COMMAND [ARGS]...

Subcommands

• reference - Cache a reference for offline use
• lookup - Show the cache path for a reference (or print file contents)

---

cache reference

Pre-fetch and cache a reference for offline use.

Usage

linkml-reference-validator cache reference [OPTIONS] REFERENCE_ID

Arguments

• REFERENCE_ID (required) - Reference ID (e.g., PMID:12345678 or DOI:10.1234/example)

Options

• --cache-dir PATH, -c PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --force, -f - Force re-fetch even if cached
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Cache a reference:

linkml-reference-validator cache reference PMID:16888623

Force refresh:

linkml-reference-validator cache reference \
  PMID:16888623 \
  --force

Custom cache directory:

linkml-reference-validator cache reference \
  PMID:16888623 \
  --cache-dir /path/to/cache

Cache a DOI:

linkml-reference-validator cache reference DOI:10.1038/nature12373

Output Format

Fetching PMID:16888623...
Successfully cached PMID:16888623
  Title: MUC1 oncoprotein blocks nuclear targeting...
  Authors: Raina D, Ahmad R, Joshi MD
  Content type: abstract_only
  Content length: 1523 characters

Exit Codes

• 0 - The public validation cache holds a current entry for the reference
• 1 - It does not

Exit 0 does not imply a download: a reference the current extractor has already cached may be reported as cached without contacting the source.

Two cases satisfy the promise loosely. Content marked as non-open full text is written to the private cache, which validation deliberately never reads, so that run exits 0 without leaving anything in the public cache. Legacy .txt entries are exempt from the extractor version check and so always report as current.

Conversely, a reference that could not be re-fetched is a failure even when a cache entry for it exists. Validation falls back to an entry written by an older extractor rather than reporting the reference as missing, but this command exists to populate the cache, so leaving it without a current entry is reported as failure and a script gating on the exit status does not go green through an outage. The same applies when no source handles the identifier at all.

Fetching PMID:16888623...
Failed to cache PMID:16888623: it could not be re-fetched, so an out-of-date cache entry was served. The cache still holds no current entry for it.

---

cache lookup

Show the cached file path for a reference, or print the cached file contents.

Usage

linkml-reference-validator cache lookup [OPTIONS] REFERENCE_ID

Arguments

• REFERENCE_ID (required) - Reference ID (e.g., PMID:12345678)

Options

• --content - Show file contents instead of just the path
• --no-cache - Bypass disk cache and fetch fresh from source
• --cache-dir PATH, -c PATH - Directory for caching references (default: references_cache)
• --config PATH - Path to validation configuration file (.yaml)
• --verbose, -v - Verbose output with detailed logging
• --help - Show help message

Examples

Show cache path:

linkml-reference-validator cache lookup PMID:16888623

Print cached content:

linkml-reference-validator cache lookup PMID:16888623 --content

Refresh then show path:

linkml-reference-validator cache lookup PMID:16888623 --no-cache

cache export

Export public bibliographic metadata to CSL JSON for Zotero import.

linkml-reference-validator cache export --output project-zotero.json [OPTIONS]

Options:

• --output PATH, -o PATH - Required destination file
• --format TEXT - Export format (default and currently supported: csl-json)
• --needs-full-text - Export only publication records needing full text (default)
• --all - Include eligible records that already contain full text
• --cache-dir PATH, -c PATH - Public reference cache directory
• --force, -f - Replace an existing output file
• --config PATH - Validation configuration file
• --verbose, -v - Enable detailed logging

linkml-reference-validator cache export \
  --cache-dir references_cache \
  --needs-full-text \
  --output project-zotero.json

The output is a DOI/PMID-deduplicated metadata allowlist. It never includes cached article content, excerpts, PDFs, local paths, or private-cache data.

---

cache enrich

Inventory or enrich existing abstract-only cache entries through one full-text provider. This is primarily intended for opt-in private-library providers such as Zotero.

linkml-reference-validator cache enrich [OPTIONS]

Options:

• --provider TEXT - Registered provider name (default: zotero)
• --cache-dir PATH, -c PATH - Reference cache directory
• --private-cache-dir PATH - Separate private research-cache destination (default: ~/.cache/linkml-reference-validator/private)
• --dry-run - Report matches without changing files (default)
• --apply - Materialize usable matches into the private research cache
• --config PATH - Validation configuration file
• --verbose, -v - Enable detailed logging

# Safe inventory
linkml-reference-validator cache enrich --provider zotero --dry-run

# Apply reviewed exact matches
linkml-reference-validator cache enrich --provider zotero --apply

The public source cache is never modified by this command, and validation never reads the private destination. Private-library content may be copyrighted; keep the research cache private.

---

Reference ID Formats

PubMed (PMID)

PMID:12345678
PMID:9876543

• Numeric identifier only
• Fetches abstract and metadata from NCBI

PubMed Central (PMC)

PMC:3458566
PMC:7654321

• Numeric identifier only
• Fetches full-text when available

DOI (Digital Object Identifier)

DOI:10.1038/nature12373
DOI:10.1126/science.1234567

• Standard DOI format (10.prefix/suffix)
• Fetches metadata from Crossref API
• Abstract availability depends on publisher

---

Configuration Notes

• The CLI currently does not read environment variables for cache dir or NCBI API keys.
• Use --cache-dir or set cache_dir in .linkml-reference-validator.yaml.
• Set email in .linkml-reference-validator.yaml for NCBI requests.

---

Shell Integration

Exit Code Usage

if linkml-reference-validator validate text \
    "MUC1 oncoprotein blocks nuclear targeting" \
    PMID:16888623 > /dev/null 2>&1; then
  echo "✓ Valid"
else
  echo "✗ Invalid"
fi

Batch Processing

for pmid in PMID:111 PMID:222 PMID:333; do
  echo "Validating $pmid..."
  linkml-reference-validator validate text \
    "some text" \
    "$pmid"
done

Piping Output

# Save output to file
linkml-reference-validator validate text \
  "..." PMID:12345678 \
  > validation_result.txt

# Grep for specific info
linkml-reference-validator validate data \
  data.yaml \
  --schema schema.yaml \
  | grep "Valid:"

---

Backward Compatibility

Old hyphenated commands still work but are deprecated:

# Old (deprecated but working)
linkml-reference-validator validate-text "..." PMID:123
linkml-reference-validator validate-data data.yaml --schema schema.yaml
linkml-reference-validator cache-reference PMID:123

# New (preferred)
linkml-reference-validator validate text "..." PMID:123
linkml-reference-validator validate data data.yaml --schema schema.yaml
linkml-reference-validator cache reference PMID:123

The old commands are hidden from --help but continue to function.

---

See Also

• Quickstart - Get started quickly
• Tutorial 1 - CLI examples
• Python API - Programmatic usage