Skip to content

Command-line interface

Run project commands through uv run from the repository root. The four public entry points are installed from pyproject.toml.

cortex-add

Create a paper summary stub and index entry.

uv run cortex-add --doi DOI --category CATEGORY [OPTIONS]
Option Meaning
--doi TEXT Required DOI; duplicate registered values fail.
--category CHOICE Required paper category from the schema.
--pdf PATH Optional existing PDF to upload through gog.
--arxiv TEXT Optional arXiv identifier.
--dry-run Fetch and display metadata without writing files or uploading.

cortex-ingest

Load registered PDFs and summaries into the hssmcortex Cognee dataset.

uv run cortex-ingest [OPTIONS]
Option Meaning
--paper TEXT Select index entries whose summary path contains the text.
--skip-drive Do not download or ingest PDFs; summaries remain eligible.
--dry-run Select and extract inputs without configuring or writing Cognee.
--reset Prune Cognee data and metadata before ingesting.
--skip-graph Use lightweight graph extraction.

cortex-query

Query an existing store. Every subcommand takes one quoted query argument.

Subcommand Default limit Result surface
search QUERY [--top-k N] 5 Semantic chunk search
graph QUERY [--top-k N] 5 Graph-completion search
summaries QUERY [--top-k N] 5 Document-summary search
ask QUERY [--top-k N] 10 Combined graph and summary reasoning

-k is the short form of --top-k for all four modes.

cortex-validate

Validate the paper index and summary frontmatter.

uv run cortex-validate [--strict]

Errors always produce a failing exit status. --strict also makes warnings fail.

Entity-resolution modules

These operator modules are not project entry points and therefore use python -m.

Command Important options
scripts.dedup_exact --apply, --no-backup
scripts.dedup_fuzzy --apply, --no-backup, --proposal-file PATH
scripts.dedup_semantic --apply, --no-backup, --threshold FLOAT, --skip-llm, --proposal-file PATH
scripts.alias_registry build Rebuild data/alias_registry.yaml.
scripts.alias_registry find NAME Resolve one canonical name or alias.
scripts.alias_registry stats Report registry totals.

Use the entity-resolution guide before any --apply operation.