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 (deepxiv ask: 300/day; deepxiv fa ask: a daily ask allowance, reset at 00:00 UTC). 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

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), --web, --search-type search|scholar|news|images, --top-k, --max-answer-tokens, --json, --all-sources. Be specific and ask for numbers; if the answer misses, rephrase rather than raising effort. Every [arXiv:ID] it cites is real — keep them. On --web, pages marked 🔗 were read only as snippets; say so.

5. 1stAuthor domains (deepxiv fa)

The loop

deepxiv fa domains                    # 12 domains, doc counts (free)
deepxiv fa spec talent                # filters, levels, extras, prices, samples (free)
deepxiv fa search talent "Geoffrey Hinton" -k 3      # → ids
deepxiv fa read talent 15023 -l brief                # cheapest card
deepxiv fa read talent 15023                         # default level (detail)
deepxiv fa ask "…" -d talent                         # cited answer (registered key, or 3 trial asks)

Always run deepxiv fa spec DOMAIN before filtering — field names, allowed operators, sort orders, read levels and prices differ per domain and are listed there. A per-domain digest is in references/fa-domains.md.

search

deepxiv fa search DOMAIN "query" [-F FILTER]... [-k N] [--offset N] [--mode M] [--sort S] [--head] [--json]

• -k 1–100 (default 10). --mode: e.g. hybrid, dense, bm25, name (talent). --sort: e.g. date, epss (cve). --head: richer hits, costs more.
• Filter-only listing: pass "*" as the query (an empty string is rejected).
• Filter syntax (validated against the spec; a bad field exits 2):

• Filter values are the database's own values. For Chinese institutions and cities they are Chinese (org=清华大学, location=北京,上海). Get real values with deepxiv fa facets DOMAIN FIELD.

read

deepxiv fa read DOMAIN ID [ID...] [-l brief|detail|full] [-e EXTRA] [-p k=v]... [-f json|md|html] [--json]

• -l brief is cheapest; default is usually detail; full is the longest (talent full = researched profile in markdown).
• -e adds one extra: talent network (coauthors/advisors/students), papers, scholar, sources; appraise honorees. Prices in the spec.
• -p passes domain parameters, e.g. appraise -p stance=positive -p org=CAS,CAE -p honoree="Yoshua Bengio"; law -p section=<chapter id> with -l full.
• Several ids in one call: deepxiv fa read talent 15023 3426 2813.
• IDs with slashes or spaces work as one quoted argument: "GB/T 42729-2023".

facets, resolve

deepxiv fa facets talent career_stage          # value → count, for -F
deepxiv fa resolve "Geoffrey Hinton" "Yann LeCun"   # names → talent ids, batch

ask (registered key; SDK token: 3 lifetime trials)

deepxiv fa ask "who works on self-supervised learning at Mila" -d talent
deepxiv fa ask "DeepSeek-R1 得到了哪些院士的正面评价" -d appraise -p paper=arxiv:2501.12948
deepxiv fa ask "个人信息出境需要满足什么条件" -d law -e medium
deepxiv fa ask "recruiting phase 3 trials for pancreatic cancer" -d trials
deepxiv fa ask "今天有哪些高危在野利用漏洞" -d cve

-e low|medium|high, -p domain params (deepxiv fa spec D lists them), --no-stream, --json, -v (tool calls on stderr). Each domain's ask answers from that domain only; to cover several, run one ask per domain (they can run in parallel) and merge. Always pass -d: auto-routing (no -d) is still early and can pick the wrong domain. Citations look like [law:…], [cve:CVE-…]; keep them.

6. Domain recipes (verified)

# talent — people
deepxiv fa search talent "Yann LeCun" -k 3                       # names: English, Chinese, pinyin, "Last, First"
deepxiv fa search talent "具身智能" -F org=清华大学 -F role=教授 -F min_h_index=30 -k 10
deepxiv fa search talent "world model" -F career_stage=student -F location=北京,上海 -k 50
ids=$(deepxiv fa search talent "world model" -F career_stage=student -k 40 --json | jq -r '.hits[].id')
deepxiv fa read talent $ids > profiles.json                      # 40 profiles in one call (~4 s)
deepxiv fa read talent 15023 -e network

# appraise — who of note cited a paper
deepxiv fa search appraise "DeepSeek-R1" -k 3                    # → arxiv:2501.12948
deepxiv fa read appraise arxiv:2501.12948 -l brief               # counts + stance breakdown
deepxiv fa read appraise arxiv:2501.12948 -p stance=positive -p org=CAS,CAE

# law / cases / us_law
deepxiv fa search law "刑法第266条" -k 3                          # statute + article number locates directly
deepxiv fa read law 刑法 -l brief
deepxiv fa search cases "网络刷单诈骗 未遂" -F province=浙江省 -F "judge_year>=2018" -k 5
deepxiv fa search cases "qualified immunity police" -F country=us -F court_level=scotus -k 5
deepxiv fa search us_law "data breach notification" -F jurisdiction=ca,ny -k 5

# trials / drugs / grants
deepxiv fa search trials "GLP-1 obesity" -F phase=PHASE3 -F overall_status=RECRUITING -k 5
deepxiv fa read trials NCT02082496 -l brief
deepxiv fa search drugs "GLP-1 weight loss" -F has_boxed_warning=true -k 5
deepxiv fa search grants "single-cell transcriptomics" -F agency=nih -F "fy>=2020" -k 5

# filings / standards / cve / fr
deepxiv fa search filings "CEO resignation" -F market=us -F event_types=officer_director_change -F "filed_year>=2023" -k 5
deepxiv fa search filings "*" -F form=10-Q -F cik=320193 --sort date -k 4
deepxiv fa search standards "锂离子电池安全" -F state=现行 -k 5
deepxiv fa read standards "GB/T 42729-2023" -l brief
deepxiv fa search cve "*" -F kev=true -F severity=critical,high --sort epss -k 10
deepxiv fa read cve CVE-2024-3400 -l brief
deepxiv fa search fr "PFAS drinking water" -F doc_type=Rule -k 5

Domain caveats worth passing on (details in the reference): model-written fields (one-liners, summaries, cve vuln_class, standards title_en) are for summarising, not quoting — quote the original-text fields and cite by id. CVE output must carry the NVD "not endorsed" notice. The standards domain is a catalogue only (no clause text).

7. Workflows

Literature survey (≈2 min for a few hundred papers):

1. 8–15 deepxiv search … --limit 100 --format json calls on sub-topics; dedupe ids.
2. --brief on the 200–400 most relevant (parallel).
3. --head + one --section on the 10–15 key papers.
4. Write the synthesis citing only papers you read, with arXiv ids.

Find people for a topic: fa search talent with career_stage / location / org / min_h_index filters → fa read talent <ids> in one batch → rank on h-index, areas and representative papers. Profiles are LLM-researched: verify before making decisions about a person, and don't publish personal details.

Who praised this paper: fa search appraise "<title>" → read -l brief for counts → read -p stance=positive (add -p org=… to narrow) → or fa ask -d appraise -p paper=<id> for a written, quote-backed summary.

Legal question across jurisdictions: run fa ask -d law, -d cases and -d us_law in parallel with the same question, then merge, keeping every citation. Answers are research aids, not legal advice; say so.

8. Cost and limits

• With a registered key, fa search/read/facets/resolve are fair use, rate-limited to 60/min, 5 at once and 5,000/day. On the auto-registered token they draw on the general daily limit at the prices in fa spec. Either way, read brief first and go deeper only for what you will use.
• fa ask draws on 1stAuthor's daily ask allowance (resets 00:00 UTC; a site-wide daily total can run out early at peak times). "今日 AI 问答额度已用完" means it is spent for today: stop asking and work from search/read.
• deepxiv ask (papers) keeps its own pool: 300/day on a registered key.
• On 429: back off for Retry-After seconds. Keep parallelism ≤ 5 per key for fa and ≤ 8 for paper --brief.

9. Errors

10. Python

import os
from deepxiv_sdk import Reader
r = Reader(token=os.environ["DEEPXIV_TOKEN"])  # Reader takes the token explicitly
r.search("world model", size=10)
r.brief("2603.19312"); r.head("2603.19312"); r.section("2603.19312", "Introduction")

fa = r.fa()                                     # FAClient, same token
fa.search("talent", "Geoffrey Hinton", top_k=3)
fa.search("cve", "*", filters={"kev": True}, sort="epss")
fa.read("talent", "15023", level="brief")
for ev in fa.ask_stream("个人信息出境需要满足什么条件", domain="law"):
    ...                                         # route, answer_delta, sources, done, error

Full references: FA.md (every fa option, events, HTTP API), USAGE.md (papers and the Python API).