Command-line (CLI) reference

PDF workflow state is stored in the central user catalog pdf-library.sqlite; use adsfolio pdf export for readable snapshots. Legacy per-root state is read without modification during migration. The user publication cache is managed by adsfolio cache status, adsfolio cache refresh, and adsfolio cache clear. Concurrent writes from two machines against the same library are unsupported; keep export snapshots as backups.

Reference hints search ADS and must agree with identifiers from the selected PDF. Recovery can use that PDF’s own DOI or arXiv ID with enabled providers. Use pdf refresh-ads --identify-scope global to select global provider settings.

pdf rename reports each unchanged or skipped filename. It uses the exact selected template without substituting another template. If a selected field lacks metadata, Rename skips the file and names the field. Add the metadata or select a template without that field. Then retry Rename.

pdf identify automatically fetches an unverified saved ADS candidate when ADS is enabled and available. Matching PDF identifiers establish verification without manual review. Valid saved proofs and cached provider records avoid that request. The GUI forwards its selected scope automatically.

Identify preserves existing CSV reports and AI input files. A new report receives a numeric suffix when its default filename already exists. Use the printed path.

adsfolio

ADSfolio research library tools.

Comprehensive Python client for NASA ADS (Astrophysics Data System).

Usage

adsfolio [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

--token <token>

NASA ADS token

Environment variables

ADS_API_TOKEN

Provide a default for --token

cache

Manage the user-level publication cache.

Usage

adsfolio cache [OPTIONS] COMMAND [ARGS]...

clear

Remove the user-level publication cache.

Usage

adsfolio cache clear [OPTIONS]

refresh

Refresh the publication cache using the saved setup profile.

Usage

adsfolio cache refresh [OPTIONS]

status

Show publication cache metadata.

Usage

adsfolio cache status [OPTIONS]

config

Manage configuration.

Usage

adsfolio config [OPTIONS] COMMAND [ARGS]...

set-token

Save API token to config file.

This token will be used by default for all NASA ADS operations when no other token is provided via environment variable or arguments.

Usage

adsfolio config set-token [OPTIONS] TOKEN

Arguments

TOKEN

Required argument

show

Show current configuration paths.

Usage

adsfolio config show [OPTIONS]

cv

Generate publication fragments for CV workflows.

Usage

adsfolio cv [OPTIONS] COMMAND [ARGS]...

generate

Query ADS and generate CV output.

Usage

adsfolio cv generate [OPTIONS]

Options

--config <config_path>

Path to cv.yaml

Default:

PosixPath('cv.yaml')

--output <output_path>

Override output file path.

--format <output_format>

Override output format from config.

Options:

latex | markdown | template

--style <style>

Override style from config.

Options:

compact | detailed | bibcode-first

--author-format <author_format>

Override author format (cv_default or ads_custom:<format>).

--dry-run

Print output to stdout without writing files.

init

Create an interactive starter cv.yaml.

Usage

adsfolio cv init [OPTIONS]

Options

--output <output_path>

Path for starter cv config.

Default:

PosixPath('cv.yaml')

--force

Overwrite output file if it exists.

--no-orcid

Do not auto-use ORCID from adsfolio set profile.

show-styles

Show compact previews for each supported rendering style.

Usage

adsfolio cv show-styles [OPTIONS]

export

Export bibliographic data.

Examples:

adsfolio export 2020ApJ…900..100S

adsfolio export 2020ApJ…900..100S 2021MNRAS.501..123A -f bibtex -o refs.bib

adsfolio export 2020ApJ…900..100S -f custom –custom “%R %T”

adsfolio export 2020ApJ…900..100S -j full # Full journal names

adsfolio export 2020ApJ…900..100S -j iso4 # ISO4 abbreviations

Usage

adsfolio export [OPTIONS] BIBCODES...

Options

-f, --format <fmt>

Export format (bibtex, aastex, mnras, custom, etc.)

-o, --output <output>

Output file

-s, --sort <sort>

Sort order

--custom <custom>

Custom format string (use with -f custom)

-j, --journal <journalname>

Journal name style: ads (macros), full, or iso4

Options:

ads | full | iso4

Arguments

BIBCODES

Required argument(s)

gui

Launch the desktop PDF library browser.

Usage

adsfolio gui [OPTIONS]

library

Manage ADS libraries.

Usage

adsfolio library [OPTIONS] COMMAND [ARGS]...

get

Get library contents.

Usage

adsfolio library get [OPTIONS] LIBRARY_ID

Options

--bibtex

Export as BibTeX

-o, --output <output>

Output file

--raw

Return raw bibcodes

Arguments

LIBRARY_ID

Required argument

list

List your libraries.

Usage

adsfolio library list [OPTIONS]

Options

-n, --rows <rows>

Number of libraries to show

--json

Output as JSON

watch

Watch a library for changes and export BibTeX.

Continuously polls the library and updates the output file when changes are detected. Useful for keeping a references.bib file in sync.

Examples:

adsfolio library watch ABC123XYZ -o refs.bib

adsfolio library watch ABC123XYZ -n 0 -t 10 # infinite, 10s interval

adsfolio library watch ABC123XYZ -j full # Full journal names

Usage

adsfolio library watch [OPTIONS] LIBRARY_ID

Options

-o, --output <output>

Output BibTeX file (default: references.bib)

-n, --num-iter <num_iter>

Number of iterations (default: 500, use 0 for infinite)

-t, --interval <interval>

Seconds between checks (default: 5)

-i, --info-interval <info_interval>

Iterations between status prints (default: 20)

-s, --sort <sort>

Sort order for export (default: ‘date asc’)

-f, --format <fmt>

Export format (default: bibtex)

-j, --journal <journalname>

Journal name style: ads (macros), full, or iso4

Options:

ads | full | iso4

-a, --additional <additional>

Additional BibTeX file to append

Arguments

LIBRARY_ID

Required argument

pdf

Identify, rename, and watch PDF files with ADS metadata.

Usage

adsfolio pdf [OPTIONS] COMMAND [ARGS]...

export

Export the SQLite registry as a human-readable JSON snapshot.

Usage

adsfolio pdf export [OPTIONS] DIRECTORY

Options

-o <output>

Required Destination JSON snapshot.

Arguments

DIRECTORY

Required argument

identify

Scan PDF files, resolve metadata, and write sidecar.

Usage

adsfolio pdf identify [OPTIONS] DIRECTORY

Options

--settings-scope <settings_scope>
Default:

'global'

Options:

global | library

--recursive, --no-recursive
--debut-year <debut_year>

Earliest year to fetch when refreshing the publication prefetch cache.

--end-year <end_year>

Latest year to fetch when refreshing the publication prefetch cache.

--clear-debut-year
--clear-end-year
--refresh-cache

Refresh the user publication cache before matching.

--output-unresolved <output_unresolved>

Move unresolved PDFs into this directory.

--clear-output-unresolved
--skip-unresolved-directory, --include-unresolved-directory

Exclude the unresolved destination before hashing or ADS work. Without –output-unresolved, the destination is DIRECTORY/unresolved.

--apply

Apply file moves: unresolved PDFs to the configured directory, and resolved PDFs from its in-library subtree back to the library root. Otherwise preview moves only.

--verbose-parser

Show low-level PDF parser warnings (useful for debugging broken PDFs).

--strategy <strategy_ids>

Enabled identification strategy; repeat in priority order.

Options:

first_page_arxiv | filename_bibcode | filename_doi | pdf_metadata_bibcode | pdf_metadata_doi | first_page_bibcode | first_page_doi | structured_filename | pdf_metadata_title | first_page_title

--allow-ads, --no-allow-ads

Allow ADS fallback without confirmation, or require confirmation. Otherwise use the saved Identify setting.

--ai-csv <ai_csv>

Path to AI-enriched unresolved CSV for additional batch identification.

-v, --verbose

Increase verbosity (use -v to print per-file unresolved move/dry-run lines).

--quiet

Disable reusable verbose logging for this run.

--provider <provider_ids>

Metadata provider priority; repeat in the desired order.

Options:

ads | crossref | datacite

--file <file_paths>

Identify only this PDF inside DIRECTORY; repeat for more files. Files in the unresolved directory are included.

Arguments

DIRECTORY

Required argument

obsidian

Generate Obsidian-friendly Markdown notes for PDFs tracked in the sidecar.

Usage

adsfolio pdf obsidian [OPTIONS] DIRECTORY

Options

--notes-dir <notes_dir>

Where to write .md notes. Defaults to DIRECTORY (colocated with the PDFs).

--force

Regenerate existing notes, replacing manual edits.

--apply

Update PDF annotations and write notes. Fetch and cache missing abstracts. Default is dry-run.

Arguments

DIRECTORY

Required argument

ocr

Route likely non-OCR PDFs into a review directory.

Usage

adsfolio pdf ocr [OPTIONS] [DIRECTORY]

Options

-o, --output <output_dir>

Directory where likely non-OCR PDFs are routed.

Default:

PosixPath('ocr_required')

--recursive, --no-recursive

Scan subdirectories recursively.

Default:

True

-m, --make-ocr-sh

Write ocrmypdf.sh in the current directory.

--apply

Apply file moves. Default is dry-run.

--verbose-parser

Show low-level PDF parser warnings while extracting first-page text.

-v, --verbose

Increase verbosity (print per-file move/dry-run lines).

Arguments

DIRECTORY

Optional argument

push-library

Push resolved bibcodes from sidecar to an ADS library.

Usage

adsfolio pdf push-library [OPTIONS] DIRECTORY LIBRARY_ID

Options

--apply

Apply remote library update.

Arguments

DIRECTORY

Required argument

LIBRARY_ID

Required argument

refresh-ads

Refresh ADS metadata, rename PDFs, and return them from unresolved.

Usage

adsfolio pdf refresh-ads [OPTIONS] DIRECTORY

Options

--bibcode <bibcodes>

Refresh one bibcode.

--identifier <identifier_input>

Refresh by Bibcode, DOI, arXiv ID, {authorLastName}-{year}-{bibstem}, or {bibstem}-{volume}-{page}. {authorLastName} is an author’s last name. {year} is the four-digit publication year. {bibstem} is the ADS journal abbreviation. The full journal name also works. {volume} is the journal volume number. {page} is the starting page or article number. Examples: Last-2020-Natur or Sci-123-45. Reference hints search ADS. If no candidate matches the PDF, its own DOI or arXiv ID can use the enabled providers.

--all

Refresh every stored bibcode, including records awaiting ADS lookup.

--pending-only

Link pending stored bibcodes using the cache first. Requires –all –no-rename.

--relative-path <relative_path>

Update this one file record from the requested ADS bibcode.

--citation-metrics

Fetch per-paper all/refereed/non-refereed citation metrics.

--rename, --no-rename

Rename refreshed PDFs. Use –no-rename to update metadata without file moves.

Default:

True

--rename-scope <rename_scope>

Use global Rename settings or this library’s settings with global fallback.

Default:

'library'

Options:

global | library

--identify-scope <identify_scope>

Choose the saved Identify settings for metadata provider order.

Default:

'library'

Options:

global | library

--output-unresolved <output_unresolved>

Override the saved unresolved directory when returning identified PDFs.

--confirm-identity

Confirm that you reviewed this one PDF and it matches the requested record, when the PDF’s own identifiers cannot prove it. Requires –relative-path. A PDF that contradicts the record is still refused.

Arguments

DIRECTORY

Required argument

rename

Rename resolved PDFs using sidecar metadata and a naming scheme.

Usage

adsfolio pdf rename [OPTIONS] DIRECTORY

Options

--settings-scope <settings_scope>

Choose saved Rename settings. Library falls back to global.

Default:

'global'

Options:

global | library

--scheme <scheme>

Rename template.

Default:

'saved Rename setting'

--author-format <author_format>

Author style: surname, surname_initials, last_comma_first, ads_custom:FMT

Default:

'saved Rename setting'

--char-policy <char_policy>

Filename handling for non-ASCII characters: ascii transliterates (Hanuš->Hanus), keep preserves Unicode.

Default:

'saved Rename setting'

--max-authors <max_authors>
Default:

'saved Rename setting'

--authors-when-truncated <authors_when_truncated>

Leading authors retained when –max-authors truncates the list.

Default:

'saved Rename setting'

--author-separator <author_separator>

Text placed between rendered authors.

Default:

'saved Rename setting'

--author-truncation-suffix <author_truncation_suffix>

Text appended to {authors} only when the list is truncated.

Default:

'saved Rename setting'

--output-unresolved <output_unresolved>

Unresolved folder; resolved files return from here to DIRECTORY. Defaults to saved Identify settings or DIRECTORY/unresolved. With –allow-ads, also move unresolved PDFs here.

--allow-ads

Identify pending PDFs before renaming. –file limits both steps.

--apply

Apply renames. Default is dry-run.

--file <file_paths>

Rename only this PDF inside DIRECTORY. Repeat for more files.

Arguments

DIRECTORY

Required argument

status

Show catalog identification and duplication status.

Usage

adsfolio pdf status [OPTIONS] DIRECTORY

Options

--recursive

Include subdirectories.

Arguments

DIRECTORY

Required argument

upgrade

Upgrade arXiv PDFs to published versions using ADS metadata.

Usage

adsfolio pdf upgrade [OPTIONS] DIRECTORY

Options

--apply

Execute upgrades. Default is dry-run.

--overwrite-arxiv-with-official

Overwrite tracked arXiv PDF with downloaded official PDF.

--arxiv-backup-if-overwritten <arxiv_backup_if_overwritten>

Backup directory for arXiv files before overwrite.

--skip-annotation-port

Skip annotation transfer from arXiv to official PDF.

--force

Force re-check even if entry already marked as published/upgraded.

Arguments

DIRECTORY

Required argument

watch

Watch directory for incoming PDFs and process continuously.

Usage

adsfolio pdf watch [OPTIONS] DIRECTORY

Options

--settings-scope <settings_scope>

Choose saved Rename settings. Library falls back to global.

Default:

'global'

Options:

global | library

--scheme <scheme>

Rename template.

Default:

'saved Rename setting'

--use-watchdog

Use watchdog backend instead of polling.

--recursive

Watch subdirectories recursively.

--interval <interval>
Default:

10.0

--output-unresolved <output_unresolved>

Move unresolved PDFs into this directory.

--author-format <author_format>

Author style: surname, surname_initials, last_comma_first, ads_custom:FMT

Default:

'saved Rename setting'

--char-policy <char_policy>

Filename handling for non-ASCII characters: ascii transliterates (Hanuš->Hanus), keep preserves Unicode.

Default:

'saved Rename setting'

--max-authors <max_authors>
Default:

'saved Rename setting'

--authors-when-truncated <authors_when_truncated>

Leading authors retained when –max-authors truncates the list.

Default:

'saved Rename setting'

--author-separator <author_separator>

Text placed between rendered authors.

Default:

'saved Rename setting'

--author-truncation-suffix <author_truncation_suffix>

Text appended to {authors} only when the list is truncated.

Default:

'saved Rename setting'

--apply

Apply renames/moves. Default is dry-run.

--auto-upgrade

Periodically upgrade arXiv entries when published versions appear.

--upgrade-interval <upgrade_interval>

Hours between ADS rechecks and auto-upgrade checks.

Default:

24.0

--overwrite-arxiv-with-official

During upgrade, overwrite tracked arXiv PDF with official PDF.

--arxiv-backup-if-overwritten <arxiv_backup_if_overwritten>

Backup directory for overwritten arXiv PDFs.

--skip-annotation-port

Skip annotation transfer when upgrading PDFs.

--force

Force upgrade checks even for entries already marked as published.

Arguments

DIRECTORY

Required argument

rate-limit

Show current rate limit status.

Usage

adsfolio rate-limit [OPTIONS]

reference

Keep external references alongside ADS records. Only export –fetch-ads needs a token.

Usage

adsfolio reference [OPTIONS] COMMAND [ARGS]...

Options

--catalog <catalog_path>

Use a separate catalog instead of the shared local library.

add

Save a manual reference without requiring a DOI or PDF.

Usage

adsfolio reference add [OPTIONS]

Options

--key <cite_key>

Required Stable LaTeX citation key.

--type <entry_type>
Default:

'misc'

--field <field_values>

Bibliographic NAME=VALUE; repeat per field.

--bibcode <bibcode>

Optional actual ADS identifier.

attach

Link an existing PDF to a reference without moving the file.

Usage

adsfolio reference attach [OPTIONS] DOCUMENT_ID PDF_PATH

Arguments

DOCUMENT_ID

Required argument

PDF_PATH

Required argument

check

Find old citation keys in a LaTeX .aux file. Show the current keys.

Run LaTeX first. The command reads the citation lines that BibTeX uses. It does not read biblatex .aux files. It does not change files.

A preprint key becomes old when ADS publishes the paper with a new bibcode. A key also becomes old when the key style changes.

Usage

adsfolio reference check [OPTIONS] AUX_FILE

Arguments

AUX_FILE

Required argument

edit

Edit one reference while keeping its local identity and attachments.

Usage

adsfolio reference edit [OPTIONS] DOCUMENT_ID

Options

--key <cite_key>
--type <entry_type>
--field <field_values>

Set NAME=VALUE; other fields are preserved.

--remove-field <removed_fields>

Remove one named field; repeat as needed.

Arguments

DOCUMENT_ID

Required argument

export

Export selected local IDs as BibTeX, including ADS and external entries.

Without –fetch-ads, the command works offline. An ADS paper without a saved ADS entry then uses its stored fields. With –fetch-ads, the command gets and saves the missing ADS entries first. It stops and writes nothing when ADS fails. An output file with the same text is not written again. As in the desktop export, the abstract and adsnote fields are left out unless –leave-out names other fields.

Usage

adsfolio reference export [OPTIONS] [DOCUMENT_IDS]...

Options

--all

Export every local reference.

-o, --output <output>

Write atomically to a .bib file; default is standard output.

--fetch-ads

First get ADS’s own BibTeX for papers without a saved copy. Needs a token.

--leave-out <leave_out>

Fields to leave out of every entry, separated by commas. Use ‘’ to keep all.

Default:

'abstract, adsnote'

Arguments

DOCUMENT_IDS

Optional argument(s)

import

Import a .bib file, or paste BibTeX through standard input (-).

Usage

adsfolio reference import [OPTIONS] [INPUT_FILE]

Options

--preview

Show parsed entries without saving references.

--source <source>

Import provenance label.

Default:

'bibtex'

Arguments

INPUT_FILE

Optional argument

keys

Show or set how BibTeX export makes citation keys.

Styles: bibcode (ADS papers only), doi, template, scholar (Google Scholar style, such as roe2021theory), and manual (type each key with set-key). A key that you set with set-key, or that came with imported BibTeX, always wins. Without options, this shows the current styles.

Usage

adsfolio reference keys [OPTIONS]

Options

--ads <ads_style>

Key style for papers with an ADS bibcode.

Options:

bibcode | doi | template | scholar | manual

--other <other_style>

Key style for papers without an ADS bibcode.

Options:

doi | template | scholar | manual

--template <template>

Template for the ‘template’ style, such as ‘{first_author_initials}{year}’.

list

List local reference IDs, including cataloged ADS documents.

Usage

adsfolio reference list [OPTIONS]

Options

--json

Include fields and attachments as JSON.

set-key

Set the citation key of one reference. Leave KEY out to remove it.

The key wins over the key style in the settings. To see reference IDs, run adsfolio reference list.

Usage

adsfolio reference set-key [OPTIONS] DOCUMENT_ID [KEY]

Arguments

DOCUMENT_ID

Required argument

KEY

Optional argument

set

Interactive first-time setup for token + identify optimization profile.

This profile is used only to reduce ADS requests during initial pdf identify. It does not constrain normal ADS searches/exports.

Usage

adsfolio set [OPTIONS]

Options

--token <token_value>

NASA ADS token.

--orcid <orcid>

ORCID identifier for publication prefetch.

--query-name <query_names>

Optional full-name query term. Repeat flag for multiple names.

--debut-year <debut_year>

Earliest publication year for prefetch window.

--end-year, --retire-year <end_year>

Latest publication year for prefetch window.

--library-id <library_ids>

ADS library ID to include in identify prefetch. Repeat for multiple IDs.