autoverse-cli

Autoverse CLI

The system-layer Skill of Autoverse. It is only responsible for enabling the Agent to correctly install, log in to, discover, and invoke the CLI.

Product chain:

scholar-relay API → autoverse CLI

The CLI is the only stable execution surface.

When to use

Use this Skill:

• The user wants to install, upgrade, or verify autoverse；
• Needs to log in, log out, switch profiles, or check identity;
• Needs to view credits, pricing, or top-up entry points;
• Needs to understand commands, flags, JSON, exit codes, or error codes;
• The CLI invocation fails and needs to recover according to structured errors;
• Development/CI needs a platform Key rather than a browser session.

Do not trigger it separately for ordinary "find papers, do a proposal, expand along seeds" requests; this Skill does not define research workflow processes or artifacts.

Installation and version

pipx install autoverse
autoverse --version
autoverse --help

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

If the user explicitly wants to upgrade:

pipx upgrade autoverse

Login and credentials

Default login:

autoverse login
autoverse whoami

• The browser completes email or GitHub confirmation by a human.
• Credentials go into the OS keychain; do not write them into paper projects, Skills, or conversations.
• Do not ask for or print API Keys.
• Only when CI / scripts explicitly need a platform Key, use AUTOVERSE_API_KEY or login --token。
• --profile <name> is a global flag, placed before the verb; different profiles use independent credentials.

Standard Agent invocation

Agent and automation invocations are fixed as:

autoverse --json --quiet <动词> ...

• On success, stdout has only one line {request_id,data}；
• On success, stderr is empty;
• On failure, stdout is empty and stderr has only one line {error:{code,message,request_id,retryable}}；
• Branch only according to code, retryable, and exit code; do not parse natural-language logs;
• Usage/input errors exit 2; runtime/auth/credits/upstream errors exit 1;
• Supports using --fields for source-side on-demand field projection; advanced debugging of the full public API goes through the api escape hatch.

When the user asks about specific commands, fields, or errors, read references/commands.md。

Functional categories and atomic commands

This Skill only provides atomic capability contracts and does not include any serial research workflow; cross-command topic investigation or citation expansion should be scheduled on demand by dedicated business Skills.

1. Account and authentication

• autoverse login: initiate OAuth browser authorization login;
• autoverse whoami: display the current logged-in identity and remaining credits;
• autoverse logout: clear local login credentials.

2. Credits and top-up

• autoverse usage: view currently available credits and the billing unit price of each command;
• autoverse topup: view plans and top-up guidance;
• autoverse topup --plan <plus|pro|ultra|test>: initiate enterprise Alipay direct top-up, automatically generate a standard PNG QR code (~/.config/autoverse/alipay_qr.png) and launch the browser checkout, silently polling until payment arrives.

3. Literature and author search

• autoverse search "<query>": search by title, keywords, and multidimensional academic conditions (supports --limit、--domain、--mode、--year-from、--year-to、--exclude、--ccf、--cast、--pku、--cscd、--cssci、--abdc、--cas、--jcr、--directory、--conference、--journal、--author、--oa、--title-only、--detailed、--fields）；
• autoverse resolve <identifier>: resolve metadata for a single document through stable identifiers such as DOI, PMID, ArXiv ID, etc.;
• autoverse batch -f <file>: batch-resolve a list of identifiers from a file (1–50 entries);
• autoverse authors "<name>": search author homepages and historical publications;
• autoverse related <id> --via <references|cited-by|similar>: Expand along references, citing documents, or similar recommendations.

4. Reference Export

• autoverse export --format <ris|bibtex|markdown> -f <json-file>: Export the JSON results saved from retrieval locally into a standard bibliographic format (0 credits, no network required).

Error Codes and Recovery Specification

CLI errors are uniformly formatted and output to stderr as JSON:{"error": {"code": "...", "message": "...", "retryable": bool, "request_id": "..."}}, following these recovery rules:

• INVALID_SESSION / NOT_AUTHENTICATED / 401: The session has expired or the user is not logged in; instruct the user to run autoverse login to complete authentication.
• INSUFFICIENT_CREDITS / 402: Insufficient credits; first run autoverse usage to confirm the balance, then prompt autoverse topup to top up; do not silently retry.
• REQUEST_OUTCOME_UNKNOWN: Network timeout and the call has generated an idempotency key; first run autoverse usage or whoami to verify whether credits were deducted/successful; do not directly resend the write request.
• ALL_SOURCES_UNAVAILABLE: The upstream academic source is temporarily rate-limited or unreachable; if retryable=true retry at most once more; if it still fails, stop, and do not falsely report the failure as "0 results retrieved".
• CURSOR_OPTION_CONFLICT: Pagination parameters conflict; when cursor is present, only the optional --limitmay be specified, and new search conditions must not be passed in at the same time.
• UNKNOWN_PLAN: The top-up package code is invalid; only plus, pro, ultra, test。
• INPUT_FILE_*: The batch input file does not exist or its encoding is not UTF-8; correct the file path and content, then retry.
• OUTPUT_FILE_*: The output target path is not writable or the directory does not exist; switch to a valid path and retry.
• RELATED_ID_*: Citation linking only accepts canonical internal IDs of academic papers; raw DOIs or strings containing slashes must not be passed in.
• retryable=true: This is a transient network or server-side glitch; retry the same logical call at most once.
• retryable=false: This is a hard business or parameter limit; terminate immediately, and do not blindly guess parameters or switch interfaces.