Command Line Interface

Archivum exposes its command line interface through the archivum console script. For library-aware work, use the Uber shell so the active library lives in the shell state.

Start Uber

Open the default library:

uv run archivum uber -a

Open a named library:

uv run archivum uber -l uber-library

Once the prompt is open, run commands directly:

stats
status
library-config
q title ~ /risk measure/ top 20
rg "spectral risk measure"
tag Wang2024 -o
stage-docs "C:\S\PDFs\Batch6"
import-bibtex "C:\S\PDFs\Batch6\bibtex-import.bib" -x

Direct Launchers

Some commands are still useful as one-shot launchers from PowerShell. The web server opens its own library context:

uv run archivum serve -b
uv run archivum serve uber-library --port 9124 --address 127.0.0.1 -b

Full Command Reference

archivum

CLI for managing bibliographic entries.

Usage

archivum [OPTIONS] COMMAND [ARGS]...

crossref

Fetch metadata from Crossref and output BibTeX.

Priority:
1. DOI (if provided)
2. Title (if provided without author/keywords)
3. Generic Search (using keywords, title, author)

Usage

archivum crossref [OPTIONS]

Options

-a, --author <author>

Author name

Default:

Sentinel.UNSET

-t, --title <title>

Title of work

Default:

Sentinel.UNSET

-d, --doi <doi>

DOI string

Default:

Sentinel.UNSET

-r, --raw

Show raw output.

Default:

False

-k, --keywords <keywords>

Search keywords

Default:

Sentinel.UNSET

delete-tag

Delete a reference from the library.

Usage

archivum delete-tag [OPTIONS] TAG

Options

-x, --execute

Actually execute.

Default:

False

Arguments

TAG

Required argument

djvu-convert-file

Convert a single DjVu file to a searchable PDF.

Usage

archivum djvu-convert-file [OPTIONS] IN_PATH OUT_PATH

Options

-v, --verbose

Show verbose output from subprocesses.

Arguments

IN_PATH

Required argument

OUT_PATH

Required argument

edit-tag

Edit a reference entry interactively.

Usage

archivum edit-tag [OPTIONS] TAG

Options

-i, --info

Show all information about the tag before editing.

Arguments

TAG

Required argument

extract-text

Manage text extraction for documents in the library.

Usage

archivum extract-text [OPTIONS]

Options

-m, --missing

Print which docs are missing their text.

-x, --execute

Actually perform the extraction/cleaning work.

-c, --clean

Find (and delete if -x) text files with no corresponding document.

-i, --info

Print info about the text: number of docs, number with text files etc.

-f, --force

Force re-extraction even if the text file already exists.

-w, --workers <workers>

Number of worker threads to use.

f

Find expr by tag or query if expr is a full query statement.

Alias for ‘q recent top 50 tag ~ expr’ (unless expr is already a full statement).

Usage

archivum f [OPTIONS] [EXPR]...

Options

-t, --table

Output in table format

Default:

False

Arguments

EXPR

Optional argument(s)

find-doc

Hash a document (or directory) and find matching records in the library.

Usage

archivum find-doc [OPTIONS] PATH

Arguments

PATH

Required argument

get-distinct-values

Display number of distinct values in each library field.

Usage

archivum get-distinct-values [OPTIONS]

Options

-f, --field <field>

Show distinct values of field in each library field.

Default:

''

hash

Get references and information by file hash (supports Regex).

Usage

archivum hash [OPTIONS] HASH_STR

Options

-o, --open

Open the document associated with the hash.

-v, --verbose

Verbosity: none (Basic), -v (Detailed Ref Info).

Default:

0

Arguments

HASH_STR

Required argument

import-bibtex

Import new references from a BibTeX file into the current library.

bibtex_path can be a path to a specific bibtex file or a directory containing a single bibtex file.

Usage

archivum import-bibtex [OPTIONS] BIBTEX_PATH

Options

-p, --doc-dir <doc_dir>

Directory containing docs referenced in the BibTeX file; defaults to the BibTeX file’s directory.

-v, --verbose

Increase verbosity: -v (Summary), -vv (Guardian Table), -vvv (Full Diagnostics).

Default:

0

-h, --add-hashes, -nh, --no-hashes

Hash input pdf files (Default: True).

Default:

True

-i, --incremental, -ni, --no-incremental

Guardian mode: Hash, check for duplicates in library, and shard/organize immediately (Default: True).

Default:

True

-t, --extract-text, -nt, --no-extract-text

Auto-run text extraction on imported files (Default: True).

Default:

True

-x, --execute

Actually perform the import; otherwise, do a dry run and report stats.

Default:

False

Arguments

BIBTEX_PATH

Required argument

library-audit

Perform a comprehensive structural audit of the library:
- Missing Files: References pointing to files that don’t exist.
- Orphan Docs: Document metadata without any reference linking to it.
- Missing Docs: References with no linked documents.
- Broken Links: ref-doc mappings with invalid tags or paths.
- Orphan Extracts: Text extracts for documents no longer in library.

Usage

archivum library-audit [OPTIONS]

Options

-v, --verbose

Show full lists of problematic items.

-x, --execute

Actually perform fixes (e.g., cleaning orphans).

library-close

Close the currently open library.

This is a command line concept; the Library class has no close method. You just delete it. It does NOT track if it is dirty and needs to change. You do not want misc. save on close behavior because it could be open on multiple machines. Collisions are not tracked.

Usage

archivum library-close [OPTIONS]

library-config

Dump the current library config file.

Usage

archivum library-config [OPTIONS]

library-copy

Copy a library folder and update its internal name.

Usage

archivum library-copy [OPTIONS] OLD_NAME NEW_NAME

Arguments

OLD_NAME

Required argument

NEW_NAME

Required argument

library-create

Create and open a new library. SEE ALSO THE CONFIG VERSION

Interactively create a YAML config file for a new library called lib_name. Save config. Then open and return the library.

Library must not already exist.

Usage

archivum library-create [OPTIONS] [LIB_NAME]...

Arguments

LIB_NAME

Optional argument(s)

library-history

Display library history based on imports.

Usage

archivum library-history [OPTIONS]

library-locate

Open explorer to see files at the location of the open library, if any.

Usage

archivum library-locate [OPTIONS]

library-open

Open a library by name and set it as current.

Usage

archivum library-open [OPTIONS] LIB_NAME

Arguments

LIB_NAME

Required argument

library-rename

Rename a library folder and update its internal name.

Usage

archivum library-rename [OPTIONS] OLD_NAME NEW_NAME

Arguments

OLD_NAME

Required argument

NEW_NAME

Required argument

library-save

Save the current library to disk.

Usage

archivum library-save [OPTIONS]

library-validate

Audit and fix library structure.

Tasks:
- sharding: verify files are in the correct hash-based folders.
- orphans: verify orphan docs are correctly sharded.
- missing: find documents in the index that don’t exist on disk.

Usage

archivum library-validate [OPTIONS]

Options

-t, --task <task>

Validation task to perform.

Default:

'sharding'

Options:

sharding | orphans | missing

-x, --execute

Actually perform the fixes; otherwise, do a dry run and report.

Default:

False

list

List all available libraries.

Usage

archivum list [OPTIONS]

Options

-d, --details

Show detailed information about each library.

Default:

False

list-stats

Display library stats for all libraries.

Usage

archivum list-stats [OPTIONS]

q

Execute a single query and return immediately.

Usage

archivum q [OPTIONS] [EXPR]...

Options

-d, --database <database>

Database (dataframe) to process. Must be “database” (default), “doc”, “ref”, or “ref-doc”.

Default:

'database'

Options:

database | doc | ref | ref-doc

-t, --table

Output results in a tabular format (default is compact).

Default:

False

-o, --output <output>

Output results to a .qmd file.

-a, --abstract

Include abstracts in the .qmd output.

Default:

False

Arguments

EXPR

Optional argument(s)

qmd-bibtex

Extract citations from a QMD file and create a BibTeX file from library matches.

Usage

archivum qmd-bibtex [OPTIONS] QMD_FILE

Options

-o, --output <output>

Alternative output BibTeX file name.

Arguments

QMD_FILE

Required argument

qmd-ref-summary

Produce qmd summary of qmd_file in directory out_path.

Makes links to all pdf files.

Usage

archivum qmd-ref-summary [OPTIONS] QMD_FILE OUT_PATH

Options

-a, --abstract

Include abstract from text extract.

Default:

False

-x, --execute

Actually execute.

Default:

False

Arguments

QMD_FILE

Required argument

OUT_PATH

Required argument

query

Interactive REPL to run multiple queries on the file index with fuzzy completion.

Usage

archivum query [OPTIONS] [START]...

Options

-d, --database <database>

Database (dataframe) to process. Must be “database” (default), “doc”, “ref”, or “ref-doc”.

Default:

'database'

Options:

database | doc | ref | ref-doc

Arguments

START

Optional argument(s)

rg

Run ripgrep with all arguments passed through unchanged.

Usage

archivum rg [OPTIONS]

rg-old

Run ripgrep (rg) with given pattern and args against text extracts from pdfs.

Usage

archivum rg-old [OPTIONS] [ARGS]...

Options

-n <n>

Number of results to return, n=-1 (default) returns all.

Default:

-1

Arguments

ARGS

Optional argument(s)

serve

Launch the web interface.

Usage

archivum serve [OPTIONS] [LIB_NAME]

Options

-p, --port <port>

Port to run the server on.

-a, --address <address>

Host address to bind to (e.g. 0.0.0.0 for all interfaces).

-b, --browser

Open browser automatically.

-d, --debug

Run in Flask debug mode (includes reloader).

--prod

Use waitress to serve in production mode.

Arguments

LIB_NAME

Optional argument

stage-docs

Prepare new documents for import by staging metadata in a BibTeX file.

1. Checks for hash duplicates in the library.
2. Extracts metadata from new files.
3. Generates a .bib file for review in Sublime Text.

Usage

archivum stage-docs [OPTIONS] DOC_PATH

Options

-f, --flag-duplicates, -nf, --no-duplicates

Check for hash duplicates in library before processing.

Default:

True

-d, --delete

Delete duplicates from source folder if found.

Default:

False

-v, --verbose

Increase verbosity.

Default:

0

-x, --execute

Actually perform the import after review.

Default:

False

-h, --enhance

Automatically enhance arXiv entries via Crossref.

Default:

True

Arguments

DOC_PATH

Required argument

stage-enhance

Enhance a staged BibTeX file with metadata from Crossref.

1. Identifies entries with ‘archivePrefix = {arXiv}’ but no ‘journal’.
2. Searches Crossref by title to find published versions.
3. Updates journal, volume, year, and DOI while keeping arXiv info.
4. Backs up the original file as .bak.

Usage

archivum stage-enhance [OPTIONS] [BIBTEX_FILE]

Options

-a, --arxiv

Perform arXiv-to-Crossref enhancement for preprints.

Default:

True

Arguments

BIBTEX_FILE

Optional argument

stats

Display library stats library.

Usage

archivum stats [OPTIONS]

status

Display library auto-reload status and file modification times.

Usage

archivum status [OPTIONS]

tag

Get documents or information by tag (supports Regex).

Usage

archivum tag [OPTIONS] TAG_REGEX

Options

-i, --information

Show information about matching entries.

Default:

True

-o, --open

Open preferred document(s) for the matched tags.

-a, --all-docs

Open all documents associated with the matched tags.

-l, --limit <limit>

Maximum number of documents to open.

Default:

5

-v, --verbose

Verbosity: none (Basic), -v (BibTeX + Docs), -vv (Full Stats).

Default:

0

-f, --file

Show the file name associated with a tag instead of the title.

Arguments

TAG_REGEX

Required argument

title

Open a document by its title with fuzzy search (no spaces!).

Usage

archivum title [OPTIONS] TITLE...

Options

-a, --all-docs

Open all docs if more than one match.

Default:

False

Arguments

TITLE

Required argument(s)

tt

Open a document by its tag and title with fuzzy search (no spaces!).

Usage

archivum tt [OPTIONS] TITLE...

Options

-a, --all-docs

Open all docs if more than one match.

Default:

False

Arguments

TITLE

Required argument(s)

uber

QT Standalone Shell. Optionally open library.

Usage

archivum uber [OPTIONS]

Options

-l, --lib-name <lib_name>

Open library.

Default:

''

-a, --auto-open

If true, auto open the default library.

Default:

False

-d, --debug
Default:

False