Command-Line Interface Reference

Complete reference for all CLI commands.

Note: All commands shown below should be prefixed with uv run when running from the project directory, or you can activate the virtual environment first with source .venv/bin/activate.

Global Options

All commands support these global options:

  • --help: Show help message and exit

  • --version: Show version information

Commands

download

Download conference papers from OpenReview API or via plugins.

Usage:

abstracts-explorer download [OPTIONS]

Options:

  • --year INTEGER: Conference year to download (required)

  • --db-path TEXT: Path to SQLite database file (required)

  • --force: Force re-download even if papers exist

  • --cache/--no-cache: Enable/disable caching (default: enabled)

Some plugins (currently AAAI) record failed page URLs in <cache>.failed.json. The next download retries those URLs automatically; delete the sidecar file to skip those retries.

Examples:

# Download 2025 papers
uv run abstracts-explorer download --year 2025

# Force re-download
uv run abstracts-explorer download --year 2025 --force

# Disable caching
uv run abstracts-explorer download --year 2025 --no-cache

create-embeddings

Create vector embeddings for semantic search.

Usage:

abstracts-explorer create-embeddings [OPTIONS]

Options:

  • --db-path TEXT: Path to SQLite database with papers (required)

  • --collection-name TEXT: Collection name in ChromaDB (default: from config)

  • --model TEXT: Embedding model to use (default: from config)

  • --force: Recreate embeddings even if they exist

  • --ignore-embedding-model-mismatch: Recreate embeddings after an embedding model mismatch without prompting

Examples:

# Create embeddings with defaults (uses EMBEDDING_DB from config)
uv run abstracts-explorer create-embeddings

# Use custom collection name
uv run abstracts-explorer create-embeddings \
    \
    --collection-name my_papers

# Force recreation
uv run abstracts-explorer create-embeddings --force

pre-process

Run the full data-preparation pipeline: download → create-embeddings → clustering pre-generate.

Usage:

abstracts-explorer pre-process [OPTIONS]

Options:

  • --conference TEXT: Limit to a single conference (default: all)

  • --year INTEGER: Limit to a single year (default: all available)

  • --force: Force re-download, reset embeddings and recompute clustering

  • --no-overlap-post-process: Run embeddings and clustering in one worker instead of overlapping them

  • --collection TEXT: ChromaDB collection name (default: from config)

  • --lm-studio-url TEXT: OpenAI-compatible API URL (default: from config)

  • --model TEXT: Embedding model (default: from config)

  • --requests-per-minute INTEGER: API rate limit, 0 disables it

  • --ignore-embedding-model-mismatch: Recreate embeddings after an embedding model mismatch without prompting

The pipeline is parallel: each conference/year unit is embedded and clustered as soon as its download finishes, while the remaining downloads keep running. Embeddings and clustering also overlap, so clustering of one unit runs while embeddings for the next unit are created. Use --no-overlap-post-process to run those two stages in a single worker. To run the steps without any post-processing, use the download, create-embeddings, and clustering pre-generate commands individually.

Examples:

# Run the full parallel pipeline
uv run abstracts-explorer pre-process

# Process a single conference and year
uv run abstracts-explorer pre-process --conference neurips --year 2025

# Recreate embeddings after switching models without prompting
uv run abstracts-explorer pre-process --ignore-embedding-model-mismatch --model my-new-model

chat

Interactive RAG-powered chat interface.

Usage:

abstracts-explorer chat [OPTIONS]

Options:

  • --db-path TEXT: Path to SQLite database (required)

  • --model TEXT: LLM model to use (default: from config)

  • --temperature FLOAT: Temperature for responses (default: from config)

  • --max-tokens INTEGER: Maximum tokens in response (default: from config)

  • --n-papers INTEGER: Number of papers for context (default: from config)

Interactive Commands:

While in the chat session:

  • Type your question and press Enter to get a response

  • exit or quit: Exit the chat session

  • reset: Reset the conversation history

  • export [filename]: Export conversation to JSON file

Examples:

# Start chat with defaults (uses EMBEDDING_DB from config)
uv run abstracts-explorer chat

# Use custom model
uv run abstracts-explorer chat --model llama-3.2-3b-instruct

# Adjust response parameters
uv run abstracts-explorer chat \
    --temperature 0.9 \
    --max-tokens 2000 \
    --n-papers 10

info

Show database information and statistics.

Usage:

abstracts-explorer info [OPTIONS]

Options:

  • --db-path TEXT: Path to SQLite database (required)

  • --show-embeddings: Also show embedding statistics

Examples:

# Basic info
uv run abstracts-explorer info

# Include embedding info
uv run abstracts-explorer info --show-embeddings

registry

Commands for sharing paper databases and embeddings via OCI container registries (e.g. GitHub Container Registry).

See the full Registry documentation for details.

registry upload

Usage:

abstracts-explorer registry upload [OPTIONS]

Options:

  • -r, --repository TEXT: OCI repository URL (e.g. ghcr.io/thawn/abstracts-data). Falls back to REGISTRY_REPOSITORY env var.

  • --token TEXT: Authentication token. Falls back to GITHUB_TOKEN env var.

  • -c, --conference TEXT: Conference to upload (case-insensitive). Use all for all conferences.

  • -y, --year INTEGER: Year to upload. Omit to upload all available years.

  • --yes: Skip confirmation prompts.

Examples:

# Upload NeurIPS 2024
abstracts-explorer registry upload -r ghcr.io/thawn/abstracts-data --conference neurips --year 2024

# Upload all NeurIPS years
abstracts-explorer registry upload -r ghcr.io/thawn/abstracts-data --conference neurips

# Upload all conferences (CI mode)
abstracts-explorer registry upload -r ghcr.io/thawn/abstracts-data --conference all --yes

registry download

Usage:

abstracts-explorer registry download [OPTIONS]

Options:

  • -r, --repository TEXT: OCI repository URL. Falls back to REGISTRY_REPOSITORY env var.

  • --token TEXT: Authentication token. Falls back to GITHUB_TOKEN env var.

  • -c, --conference TEXT: Conference to download (case-insensitive). Use all for all conferences.

  • -y, --year INTEGER: Year to download. Omit to download all available years.

  • --embedding-model TEXT: Embedding model name (used to derive the tag when no local data exists).

  • --yes: Skip confirmation prompts (also auto-confirms clear-and-retry on model mismatch).

Examples:

# Download NeurIPS 2024
abstracts-explorer registry download -r ghcr.io/thawn/abstracts-data --conference neurips --year 2024

# Download with explicit embedding model (when local DB is empty)
abstracts-explorer registry download -r ghcr.io/thawn/abstracts-data --conference neurips --year 2024 \
  --embedding-model text-embedding-qwen3-embedding-4b

# Download all (CI mode)
abstracts-explorer registry download -r ghcr.io/thawn/abstracts-data --conference all --yes

registry list

Usage:

abstracts-explorer registry list [OPTIONS]

Options:

  • -r, --repository TEXT: OCI repository URL. Falls back to REGISTRY_REPOSITORY env var.

  • --token TEXT: Authentication token. Falls back to GITHUB_TOKEN env var.

  • --tag TEXT: Inspect a specific tag and display its metadata.

Examples:

# List all tags
abstracts-explorer registry list -r ghcr.io/thawn/abstracts-data

# Inspect a specific tag
abstracts-explorer registry list -r ghcr.io/thawn/abstracts-data \
  --tag neurips-2024_text-embedding-qwen3-embedding-4b

Environment Variables

All CLI commands respect configuration from environment variables and .env files. See the Configuration page for details.

Exit Codes

  • 0: Success

  • 1: General error

  • 2: Invalid arguments or options