CLI and Python workflows

Use the App GUI guide for interactive library management. This page covers scripts and the Python client.

Learning path:

  1. Install and configure ADS access on this page.

  2. Follow the tutorials in order: setup and search, export and BibTeX, ADS libraries, PDFs, operations, CVs, and a Python script.

  3. Look up details in the command-line reference and the Python API.

Install

ADSfolio requires Python 3.10 or newer. Install the current PyPI release:

pip install adsfolio            # CLI and Python client
pip install "adsfolio[full]"    # adds PyMuPDF text extraction and folder watching
pip install "adsfolio[full,gui]"  # adds the desktop application

uv tool install adsfolio or pipx install adsfolio installs the CLI in its own environment.

CLI and API without the desktop app

The base package includes the CLI and Python API. It does not install Qt, PyMuPDF, Watchdog, or the native desktop bundle. It still includes basic PDF and citation dependencies. Python remains necessary for this installation.

For an AI agent or script, use JSON output:

adsfolio search 'author:Einstein' --fields bibcode,title,year --rows 5 --json

Without a persistent CLI installation, use:

uvx --from adsfolio adsfolio search 'author:Einstein' --rows 5 --json

ADS queries require an ADS token. Provide ADS_API_TOKEN through your environment or secret manager. Do not place tokens in agent instructions or command arguments. For repeatable environments, pin the package to your chosen release.

Download the CLI/API agent skill. Save it as adsfolio-cli-api/SKILL.md in your agent’s skills directory. The skill covers queries, JSON output, Python access, and mutation boundaries.

From source

git clone https://github.com/ysBach/adsfolio.git
cd adsfolio
uv sync --all-extras
uv run adsfolio --help
uv run adsfolio-gui      # the desktop app from this checkout

uv sync creates the project’s .venv. Do not synchronize a shared environment. Prefix the commands below with uv run when using this checkout. Homebrew installations already provide the adsfolio command.

Configure ADS access

ADSfolio uses the official NASA ADS API for searches, citation exports, metrics, ADS libraries, and journal information. The linked ADS repository provides API documentation and examples. ADSfolio is an independent project, not an official ADS application.

Get your token from ADS settings. Use the desktop token dialog, or run interactive setup:

adsfolio set

Setup saves your token and publication profile. It also builds the publication cache. You can supply ADS_API_TOKEN through your environment instead. Local references and DOI lookups do not require an ADS token.

Search and export

adsfolio search "author:Einstein" --fields bibcode,title --rows 5
adsfolio export 2020ApJ...900..100S -f bibtex
adsfolio library list
adsfolio library get LIBRARY_ID --bibtex

Replace LIBRARY_ID with your ADS library identifier. See search, export, and remote libraries.

Identify and rename local PDFs

adsfolio cache status
adsfolio pdf identify ~/Papers --recursive
adsfolio pdf rename ~/Papers
adsfolio pdf rename ~/Papers --apply

Identify records publication matches. Rename previews changes unless you supply --apply. Inspect the preview before applying it. Both commands check each match against the arXiv stamp and DOIs that the PDF states about itself. They skip PDFs whose identifiers contradict the record or cannot confirm it. See PDF identity checks. ADSfolio recognizes supported display markup in provider titles during the title comparison. The record must still pass the other identity checks.

To retry verified external metadata without an ADS bibcode, enable ADS and allow ADS requests. This command selects ADS for one run:

adsfolio pdf identify ~/Papers --provider ads --allow-ads

A verified ADS match can add its bibcode. ADSfolio may also use a cached ADS record without network permission. If no ADS match passes the identity check, it keeps the existing metadata. Check the output before retrying.

pdf rename and pdf watch load saved global Rename settings by default. Add --settings-scope library to use the library’s saved Rename settings. If the library has no saved settings, ADSfolio uses the global settings. Explicit Rename flags, such as --scheme, override the named settings for that run.

If a template field lacks metadata, Rename skips the file and names the missing fields in its output. Add the metadata or choose a different --scheme. Then retry the rename.

See PDF workflows for provider order, filename templates, OCR preparation, watching, and annotation transfer.

The catalog stores file locations, metadata, and history outside your PDF folders. Use adsfolio pdf export DIR -o snapshot.json for a readable registry backup. Keep a database backup when testing migrations or changing library tools.

Watch, upgrade, and export notes

adsfolio pdf watch ~/Papers --recursive --apply
adsfolio pdf upgrade ~/Papers
adsfolio pdf obsidian ~/Papers
adsfolio pdf status ~/Papers --recursive

Watch with --apply can identify and rename arriving PDFs that pass the identity check. A unique exact ADS bibcode in a filename can associate a PDF without independently verifying its contents. Review saved policies before starting Watch on an existing collection. For a proven incremental annotation save, Watch keeps the saved identification. Other changes still need an identity check. Watch also rechecks existing records with enabled ADS at startup and every 24 hours. Set --upgrade-interval to change the interval. A verified new match or bibcode updates metadata and uses the saved Rename settings with --apply. Without --apply, it previews those changes. A failed identity check or filename collision keeps the files in place. Resolve the reported issue and retry. The recheck does not open a PDF when ADS returns its stored bibcode. With --apply, it remembers failed identity checks for each library. It skips those PDFs until the PDF, its saved identifiers, or the ADS record changes. If the template requires missing metadata, Watch keeps the filename and reports the missing fields. Add the metadata or choose another template before retrying. Upgrade and Obsidian commands preview their work by default. Read their --help output before applying changes.

See operations and troubleshooting and CV workflows for further examples.

Python client

from adsfolio import ADSClient

client = ADSClient()
try:
    results = client.search.query(
        "author:Einstein", fl=["bibcode", "title"], rows=5
    )
    bibtex = client.export.export(["2020ApJ...900..100S"], format="bibtex")
    libraries = client.libraries.list_libraries()
finally:
    client.close()

See the API reference for public modules and interfaces. The query-to-document example covers a complete bibliography workflow.

Tutorials

Follow the tutorials in order. Each one builds on the previous one.

ADS search and libraries:

  1. Setup and first search

  2. Export and BibTeX

  3. Library workflows

PDFs, operations, and documents:

  1. PDF workflows

  2. Operations and troubleshooting

  3. CV workflows

  4. From an ADS query to a document with Python

For a PDF without a readable own identifier, review the PDF and use pdf refresh-ads ROOT --identifier ID --relative-path FILE --confirm-identity. This confirms one file. It cannot override a conflicting identifier or an own identifier that the provider does not corroborate.