/deepxiv-cli

name: deepxiv-cli
version: "1.2.1"
description: Use the deepxiv CLI to search and read academic papers (arXiv, PMC, bioRxiv, medRxiv) section by section, get cited answers from papers or the web, and query 1stAuthor's domains with the same token — AI researchers and their profiles, which academicians and fellows cited a paper, Chinese and US statutes, court judgments, clinical trials, drug labels, research grants, company filings, Chinese national standards, CVEs and the US Federal Register. Use when a task needs papers, people, legal or regulatory text, trials, drugs, grants, filings, standards or vulnerabilities as evidence.
frameworks: ["claude-code", "codex", "langchain", "custom-agents"]
use_cases: ["literature-search", "paper-analysis", "talent-search", "citation-appraisal", "legal-research", "clinical-trials", "regulatory-research", "security-research"]

DeepXiv CLI

One CLI, one token: papers (`search`, `paper`, `pmc`, `trending`, `ask`) plus 12 1stAuthor domains (`deepxiv fa …`). Everything below was run against production on 2026-10-12 with deepxiv-sdk 1.2.1.

1. Setup

pip install -U deepxiv-sdk          # `deepxiv fa` needs 1.2.0+, `fa search --sort` 1.2.1+
deepxiv --version
deepxiv token                       # shows the active token

• **Token**: the first call auto-registers a free token and saves it to `~/.env`

(`DEEPXIV_TOKEN`). Every command also takes `-t TOKEN`.

• **Registered key**: the agentic calls need one (300/day free). On the

auto-registered token, `deepxiv ask` returns **403**; `deepxiv fa ask` works **3 times in total** (stderr: `🎟️ 试用剩余 N/3 次 · Free trial: N of 3 asks left`), then returns 403. Tell the user to register at https://data.rag.ac.cn/register and run `deepxiv config --token THEIR_KEY`. Don't spend the trial on throwaway questions, and don't retry a 403. Search and read work on either token.

• **No other keys**: 1stAuthor domains go through deepxiv with the same token.

2. Which command

| The task needs… | Command | |---|---| | An answer, with citations, from the literature | `deepxiv ask "…"` | | An answer about anything non-academic (news, products, pricing) | `deepxiv ask "…" --web` | | Papers on a topic | `deepxiv search "…"` | | One paper, as cheaply as possible | `deepxiv paper ID --brief` → `--head` → `--section NAME` | | Biomedical full text | `deepxiv pmc PMCID`, `deepxiv search "…" --biorxiv/--medrxiv` | | What's hot on arXiv | `deepxiv trending --days 7` | | People: researchers, students, profiles, coauthors | `deepxiv fa … talent` | | Which academicians / fellows cited a paper, and what they said | `deepxiv fa … appraise` | | Statutes (China and 25 other jurisdictions) | `deepxiv fa … law` | | Court judgments (China, US) | `deepxiv fa … cases` | | US statutes, regulations, agency decisions | `deepxiv fa … us_law` | | Clinical trials (ClinicalTrials.gov) | `deepxiv fa … trials` | | US drug labels (openFDA) | `deepxiv fa … drugs` | | NSF / NIH grants | `deepxiv fa … grants` | | Company filings (SEC, China) | `deepxiv fa … filings` | | Chinese national standards (GB, GB/T) | `deepxiv fa … standards` | | Vulnerabilities (NVD + CISA KEV + EPSS) | `deepxiv fa … cve` | | US Federal Register | `deepxiv fa … fr` | | A cited answer over one of those domains | `deepxiv fa ask "…" -d DOMAIN` |

**Prefer `ask` when the user wants an answer**, and search/read when they want the documents themselves, a complete list, or numbers you will compute on.

3. Output contract (all commands)

• **stdout is data only**: hits, documents, answers, or JSON with `--json`

(`--format json` for `search`). **stderr** carries quota, progress, routing, sources, hints and errors. So `> file` and `| jq` get clean data.

• **Exit codes**: `0` success · `1` API/network error (401, 403, 429, 4xx, 5xx,

or an error during `ask`) · `2` bad usage (unknown filter field, bad value).

• **Quota line** on stderr after every `fa` call: `💳 cost 2 · 9990/10000 left today`.

4. Papers

Search

deepxiv search "speculative decoding" --limit 10
deepxiv search "world model" --date-from 2025-01 --min-citations 20 --limit 20
deepxiv search "LLM agents" --categories cs.AI,cs.CL --venue NeurIPS --venue-year 2025
deepxiv search "protein design" --biorxiv --limit 5
deepxiv search "world model" --limit 100 --format json | jq -r '.result[].arxiv_id'

Options: `--limit 1..100`, `--offset`, `--categories`, `--authors`, `--orgs`, `--venue` (repeatable), `--venue-year`, `--min-citations`, `--date-from/--date-to` (YYYY, YYYY-MM or YYYY-MM-DD), `--use-fine-rerank`. JSON hits carry `arxiv_id, title, tldr, abstract, authors, date, citation_count, categories, venue, github_url`.

Read progressively — the main token saver

deepxiv paper 2603.19312 --brief                 # ~300 tokens: TLDR, keywords, citations, GitHub
deepxiv paper 2603.19312 --head                  # section list with per-section TLDR and token_count (JSON)
deepxiv paper 2603.19312 --section "Introduction"  # one section
deepxiv paper 2603.19312 --preview               # first ~10k chars
deepxiv paper 2603.19312                         # full text (often 20–50k tokens)
deepxiv paper 2603.19312 --popularity            # social signal
deepxiv paper 10.1101/2021.02.26.433129 --biorxiv
deepxiv pmc PMC544940 --head

Rule: `--brief` to decide, `--head` to find the section, `--section` to read it. Pass section names exactly as `--head` prints them (including odd escapes like `\&`). For hundreds of papers, run `--brief` in parallel (`xargs -P 8 -I{} deepxiv paper {} --brief`) — 340 briefs take ~16 s.

Ask (registered key)

deepxiv ask "what speedup does speculative decoding report on HumanEval"
deepxiv ask "compare methods for MoE routing collapse" --effort high
deepxiv ask "NeurIPS 2025 best paper" --web --search-type news
deepxiv ask "…" > answer.md          # answer only; sources stay on stderr

`--effort default|high|xhigh` (more reading rounds)