# Getting started

## Install

This guide covers ADSfolio {sub-ref}`release`.

For queries or AI agents, install `adsfolio` from PyPI instead of downloading the desktop app.
This provides the CLI and Python API without Qt or the native app bundle.
See [CLI/API installation and the agent skill](command-line-and-python.md#cli-and-api-without-the-desktop-app).

1. Download the file for your system from
   [GitHub Releases](https://github.com/ysBach/adsfolio/releases/latest).
2. Install it as the table shows.
3. Open ADSfolio.

| System | File | Install |
| --- | --- | --- |
| macOS 15 or later, Apple silicon | `adsfolio-macos-arm64.dmg` | Open the file and drag `ADSfolio.app` to Applications. |
| macOS 15 or later, Intel | `adsfolio-macos-x86_64.dmg` | Open the file and drag `ADSfolio.app` to Applications. |
| Windows x86-64 | `adsfolio-windows-x86_64.zip` | Extract the file and open `adsfolio.exe` in the `adsfolio` folder. |
| Linux x86-64, glibc 2.39 or later | `adsfolio-linux-x86_64.tar.gz` | Extract the file and run `adsfolio` in the `adsfolio` folder. |

On Windows and Linux, keep the extracted `adsfolio` folder together. The program
needs all of its files.

The app is not signed. The first time you open it, macOS can block it. Open
**System Settings → Privacy & Security**. Choose **Open Anyway** only if you
trust the download. Windows can show a publisher warning.

With Homebrew on macOS, run `brew install --cask ysBach/adsfolio/adsfolio`.
For the command line and Python, see [CLI and Python](command-line-and-python.md).

The app includes Python. You need no ADS token to browse your PDFs. When a new
version is available, **App Update** in the toolbar shows a blue dot. A new
version keeps your library, settings, and token.

## Watch the first run

<video controls muted playsinline preload="metadata" width="100%"
  poster="_static/welcome.png">
  <source src="_static/tutorial/first-run.mp4" type="video/mp4">
</video>

The video shows these steps with fictional sample papers:

1. A new installation opens with three setup steps.
2. **Add PDF Folder…** selects a folder of papers.
3. ADSfolio asks whether to include subfolders.
4. ADSfolio asks whether to watch the folder for new PDFs.
5. **OK** in the Identify prompt finds publication details.
6. The library lists papers and their details.

It ends with the optional token and profile windows and **Software Update**.

## Add your existing folders

1. Open ADSfolio. A new installation shows **Welcome to ADSfolio** with three
   steps. Setup requires only the PDF folder.
2. Choose **Add PDF Folder…** (or **File → Add Library Root…**).
3. Select your PDF folder.
4. If the folder has subfolders, choose **Include Subfolders** or
   **This Folder Only**. You can change this later with **Include Subdirectories**.
5. Choose a watch option for new PDFs in this folder:
   - **Watch, Identify, and Rename** processes each new PDF automatically.
   - **Watch and Notify Only** shows a notice for each new PDF.
   - **Do Not Watch** (the default) turns watching off.

![Welcome page with three setup steps](_static/welcome.png)

![Question that asks whether to include subfolders](_static/tutorial/subfolder-question.png)

![Question that asks whether to watch the new library](_static/tutorial/watch-question.png)

Each library has its own watch settings. Hover over a library in the sidebar
to see them. Change them later on the library's context menu.

Adding a root records file locations. It does not move your PDFs.
The identification prompt opens next. Choose **OK** to start, or **Cancel** to
browse first.
You can browse your library without an ADS account.
Start with one folder before processing a large collection.

## Identify papers in a batch

1. Open **Identify**. Adding a folder also opens this prompt.
2. Read the lookup scope and choose **OK**.
3. Enter an ADS token if setup appears.
4. Review the results and job log.

![Identify prompt that explains the lookup before it starts](_static/tutorial/identify-prompt.png)

The token window opens only when ADS needs a token. **Test Token** sends one
search request to ADS and shows whether ADS accepts the token.

![NASA ADS token window with Save, Test Token, and Cancel](_static/tutorial/token-dialog.png)

Select **Advanced options…** to change evidence sources or DOI provider order.
To keep ADS fallback enabled, choose **All libraries** or **This library only**.
Enable **Allow ADS fallback**. Choose **Save Defaults**. Later Identify runs
restore that choice. See [saved Identify defaults](gui.md#save-ads-fallback-for-later-runs).

The lookup keeps filenames and file locations. Locked fields and history stay
intact. Identification can update unlocked publication fields.

Identification checks saved results before online lookups.
The default provider order is ADS, Crossref, then DataCite.
Crossref and DataCite look up exact DOIs without an ADS token.
ADS title searches require your token.
Set it through **Tools → NASA ADS Token…** when requested.

Processing time depends on PDF text, cached results, provider limits, and your
connection. Scanned PDFs may need external OCR first. ADSfolio does not bundle OCR.
OpenAlex and PubMed lookup are not supported.

## Review metadata before renaming

A bibcode identifies a publication. It does not prove that the current PDF
matches that publication. Before ADSfolio saves metadata or renames a PDF, it
compares the record with the arXiv stamp and DOIs that the PDF states about
itself. A contradiction blocks the change. A PDF without such identifiers needs
your explicit confirmation. File names, title similarity, and author similarity
do not count as proof. See [PDF identity checks](gui.md#pdf-identity-checks).
Stored citation fields can remain available while file verification is
pending. Inspect the status tooltip for the reason.

![Library window with sample papers and the details of one paper](_static/app-overview.png)

1. Select a paper and inspect its metadata.
2. Correct fields when necessary.
3. Open **Rename**.
4. Review the filename preview.
5. Apply the changes you accept.

You can rename papers with sufficient metadata without an ADS bibcode.
Use **File → Local References…** for manual entries or BibTeX imports.
See [My paper is not on ADS](local-references.md).

## Find a paper

Type in the **Find** field above the table. Words separated by spaces must
all match. Search ignores accents and letter case, so `doremont` finds
`Dorémont`. To search one field, type its name and a colon:

```text
author:"Dorémont-Roe" year:2026 comet
```

A list suggests field names and stored values while you type. Found text is
highlighted in the table. See [Search the table](gui.md#search-the-table)
for all fields and options.

## Keep the library current

Press **F5** after moving or deleting files outside ADSfolio.
Local refresh reconciles file facts. ADS refresh retrieves remote metadata.
Permanent cleanup is separate.

The catalog stores metadata, file locations, and version history outside the app.
Replacing the application does not delete that catalog.
If you are upgrading from the earlier application, close it and open ADSfolio
**0.6.0** once before installing the current version. Version 0.6.0 converts the catalog
and imports earlier per-library files. Current versions copy earlier data
directories but no longer convert their reserved metadata keys. Without that
conversion, earlier manual locks, author text, and local references are not
honoured. Keep the original data until you check the converted library.
If you already used ADSfolio 0.6.0, you can upgrade directly.

See the [App GUI guide](gui.md) for settings and folder watching.
See [CLI and Python workflows](command-line-and-python.md) for scripts and APIs.