@mantra-ai/cli

The open-source hypothesis generator hooked to Claude Code.

Discover papers across your Zotero library, local PDFs, and the mantra store. Mantra resolves metadata, fetches open-access full text, and normalizes everything into a structured local library backed by SQLite.

Install

npm install -g @mantra-ai/cli

Supports macOS (Apple Silicon & Intel) and Linux (x64 & ARM64).

Quick start

mantra init "my-review"                  # start a project
mantra discover CRISPR off-target        # search all sources, pick papers to add
mantra discover 10.1038/s41586-024-07487-w  # add by DOI directly
mantra hypothesize                       # generate hypotheses from project papers

Discover

discover is the primary way to find and add papers to a project. It searches across all configured sources transparently:

• Mantra store — papers you've previously added
• Zotero catalog — title and author search in your Zotero library
• PDF directories — indexed PDFs with extracted DOIs

mantra discover genome editing techniques    # search all sources
mantra discover --select all CRISPR          # add all matches non-interactively
mantra discover --select 1,3 protein folding # add specific results
mantra discover 10.1234/example 2301.07041   # add by DOI or arXiv ID

Results from multiple sources are merged by DOI, so a paper in both your Zotero and mantra store appears once. When you select a paper from Zotero or a PDF directory, it's automatically ingested into the mantra store and linked to your project.

Direct ingestion

Use add to ingest papers directly without a project context:

mantra add 10.1038/s41586-024-07487-w   # add by DOI
mantra add paper.pdf                     # add from a local PDF

Batch ingestion

mantra add 10.1038/s41586-024-07487-w 10.1126/science.adg7879 PMC9876543 arXiv:2301.07041
mantra add --file dois.txt --delay 500   # from file, with rate limiting

Commands

| Command | Description | |---|---| | init <name> | Initialize a project in the current directory | | discover [inputs...] | Find papers across all sources and add to current project | | add [inputs...] | Add papers by DOI, PMID, PMCID, arXiv ID, or PDF path | | papers | List papers in the library or current project | | show <id> | Show full details for a paper | | search <query> | Full-text search with snippets | | export | Export as BibTeX, JSON, or CSV | | update [id] | Re-resolve metadata from upstream sources | | remove <id> | Remove a paper from the library or unlink from a project | | library | Show library stats | | config | Manage settings and API keys | | setup | Run (or re-run) the interactive setup wizard |

Use mantra <command> --help for detailed options.

How it works

When you add a paper, Mantra:

1. Detects the identifier type (DOI, PMID, PMCID, arXiv ID) and resolves all cross-references via Crossref, OpenAlex, EuropePMC, and source-specific APIs
2. Fetches the full text using a prioritized chain of open-access sources, preferring structured JATS XML when available
3. Normalizes the content into a canonical structured format with sections, blocks, citations, and metadata. For PDFs without JATS XML, it uses Gemini to extract structure
4. Stores everything locally in a SQLite database with full-text search

Supported sources

Crossref, OpenAlex, EuropePMC, bioRxiv, medRxiv, arXiv, PLOS, Zotero (local).

Projects

Mantra organizes papers into per-directory projects. Run mantra init to create a project, then use discover to find and curate papers from all your sources.

mkdir my-review && cd my-review
mantra init "my-review"
mantra discover protein aggregation     # searches Zotero, PDFs, and mantra store
mantra discover --select all amyloid    # add all matches non-interactively
mantra papers --project                 # list this project's papers

Configuration

mantra config list          # view all settings
mantra config set key val   # set a config value
mantra config path          # show config file location

Source configuration

Configure local sources so discover can search across them:

mantra config set zoteroPath ~/Zotero     # Zotero data directory
mantra config set pdfDirs ~/Papers        # PDF directories to index

These are auto-detected during mantra setup if Zotero is installed.

API keys

For PDF-to-structured-text conversion (when JATS XML is unavailable), set a Gemini API key:

mantra config set geminiApiKey YOUR_KEY

Or use the environment variable GEMINI_API_KEY.

Global options

| Flag | Description | |---|---| | --json | Output as JSON | | --no-interactive | Suppress interactive prompts |

License

MIT