Autoverse

Command-line client for Autoverse literature search. The default API is https://app.autoverse.nz.

pipx install autoverse
autoverse login
autoverse whoami
autoverse search "HER2-low breast cancer" --domain medicine --limit 5
autoverse resolve doi:10.4143/crt.2023.1138
autoverse related pmid:38291745 --via references --limit 5
autoverse usage
autoverse topup
autoverse update --check

autoverse login opens a browser confirmation page on the Autoverse site (email or GitHub). Credentials go into the OS keyring. Named profiles use --profile and do not share the file fallback with default.

whoami shows the signed-in account and remaining credits. usage shows credits and recent usage. topup prints the registered email and the three store pack links; it does not charge. autoverse --help shows the Autoverse wordmark.

autoverse update --check checks PyPI without modifying the installation. Human terminals may show one cached update hint per 24 hours; --json --quiet output never receives ambient notices. Set AUTOVERSE_NO_UPDATE_NOTICE=1 to disable the human hint.

CI and scripts can store a console platform key instead:

autoverse login --token sr_live_...
# or
export AUTOVERSE_API_KEY="sr_live_..."

Do not commit the key. Agents use the same CLI commands and machine-readable --json output; official scenario Skills compose the CLI rather than a separate tool protocol.

For automation, put global flags before the command and parse stdout only:

autoverse --json --quiet search "retrieval augmented generation" --limit 5

Failures are one JSON object on stderr with error.code, request_id, and retryable; stdout remains empty.

Curated paper commands now keep the same public research fields across search, resolve, batch, and related: full authors, publication types, public identifiers, per-source citation counts, OA information, subjects, dates, and venue metadata. Internal routing, billing, provider status, provenance, and raw upstream objects remain available only through the API escape hatch. authors also returns aliases, paper count, citation counts, H-index, and external IDs.

An empty successful search still exits 0. If every usable source failed and the server returns only partial=true warnings with no papers, the CLI emits ALL_SOURCES_UNAVAILABLE on stderr and exits 1 instead of presenting an empty result as success.

Requires Python 3.12+. The package and the command are both autoverse.

Internal design lives under doc/ (start at doc/README.md). Official system and scenario Skills live under skills/, not inside the wheel.