DeepXiv CLI#

deepxiv is a progressive-reading paper tool for open-access literature (arXiv, PMC, Semantic Scholar) with optional web search and an LLM-powered research agent.

The single most important rule: read the smallest amount of text that answers the question. Climb the ladder only as far as needed.

Progressive reading ladder#

For any paper, prefer the cheapest rung that still answers the question:

RungCommandWhat you getWhen to use1paper <id> --briefTitle, TLDR, keywords, citations, GitHub URLFirst triage of any paper2paper <id> --headMetadata + section list (JSON)Decide which sections matter3paper <id> --previewFirst ~10k chars (intro + early method)Need more than TLDR but not full sections4paper <id> --section <Name>One named sectionTargeted answer (Method / Results / etc.)5paper <id> or --rawFull markdownOnly when explicitly required

Never jump to rung 5 unless the user asked for a full read or the task truly needs it.

Setup#

Before using deepxiv, verify it is available:

bash

deepxiv --help

If missing, stop and tell the user — do not install it on your own. If the user asks you to install it, follow references/install.md, which has per-OS instructions, and only run install commands after the user explicitly approves them. deepxiv requires Python 3.10+.

Health and diagnostics (safe to run any time):

bash

deepxiv health     # API + token reachability check
deepxiv debug      # environment diagnostics

Decision: which command do I want?#

User wants…Start with"Find papers about X"search (with filters if narrow)"What's hot recently in X?"trending"Explain this paper" (has ID)paper --brief → --head → section"Compare these N papers"paper --brief for each, then targeted sectionsBiomedical / PubMed paperpmc <PMC_ID>Has only Semantic Scholar IDsc <id>"Who is this author / what's this project?"wsearch"Is this paper actually getting traction?"paper --popularityOpen-ended multi-step research questionagent query (see caveats)

Core commands#

search — arXiv search with filters#

bash

deepxiv search "agent memory" --limit 5
deepxiv search "multimodal reasoning" --limit 10 --format json

Filters (combine freely):

bash

# Category filter (arXiv categories)
deepxiv search "retrieval" --categories cs.IR,cs.CL --limit 5

# Date window
deepxiv search "diffusion" --date-from 2025-01-01 --date-to 2025-06-30

# Citation floor — useful to skip obscure preprints
deepxiv search "world model" --min-citations 50 --limit 5

# Search mode: hybrid (default), bm25 (literal), vector (semantic)
deepxiv search "chain of thought" --mode bm25 --limit 5
deepxiv search "models that can think before answering" --mode vector

Defaults:

• --limit 3 to 5 for triage; raise only when explicitly needed
• --format json whenever you intend to post-process (pipe to jq)
• Use bm25 for exact phrasing, vector for fuzzy concepts, hybrid otherwise

paper — get an arXiv paper#

bash

deepxiv paper 2409.05591 --brief        # rung 1
deepxiv paper 2409.05591 --head         # rung 2
deepxiv paper 2409.05591 --preview      # rung 3
deepxiv paper 2409.05591 --section Method   # rung 4
deepxiv paper 2409.05591                # rung 5 — full
deepxiv paper 2409.05591 --popularity   # social impact / trending signal
deepxiv paper 2409.05591 --raw          # raw markdown (full)

Section names come from --head. Common names: Introduction, Related Work, Method, Experiments, Results, Discussion, Limitations, Conclusion. Names are paper-specific — do not guess; check --head first if unsure.

Use --popularity when the user asks "is this paper a big deal" or you need to rank by attention rather than citations.

pmc — PubMed Central / biomedical#

bash

deepxiv pmc PMC544940 --head
deepxiv pmc PMC544940

PMC currently returns JSON only. Use when the target is biomedical or a PMC ID is given.

sc — Semantic Scholar lookup#

bash

deepxiv sc 258001
deepxiv sc 258001 --json

Use when the user gives a Semantic Scholar ID, or when you need richer metadata (citation graph, author info) for an arXiv paper that you have already cross-referenced.

trending — hot papers#

bash

deepxiv trending --days 7 --limit 10 --json
deepxiv trending --days 30 --limit 5

--days accepts only 7, 14, or 30. Use for weekly digests and "what's hot" requests.

wsearch — web search#

bash

deepxiv wsearch "karpathy"
deepxiv wsearch "DeepSeek R1 release notes" --json

Use for non-paper context: author background, project home pages, blog posts, release announcements. Cheap and broad — good for grounding before a paper read.

agent query — LLM-powered research agent#

bash

deepxiv agent query "Compare RAG vs long-context for code QA"
deepxiv agent query "Latest agent memory papers" --max-turn 10 --verbose

This is a multi-turn research agent that can search and read papers on its own. Caveats:

• Requires the user to run deepxiv agent config once to set up their preferred LLM
• Consumes LLM usage on the user's account
• Slower and less predictable than manual search + paper flows
• Prefer manual progressive reading by default; reach for agent query only when the question is genuinely open-ended and the user has agreed to the cost

JSON post-processing#

When you need to slice search/trending output, prefer JSON + jq over re-running text searches:

bash

deepxiv search "agent memory" --limit 10 --format json \
  | jq -r '.[] | "\(.arxiv_id)\t\(.citations // 0)\t\(.title)"' \
  | sort -k2 -n -r

deepxiv trending --days 7 --limit 20 --json \
  | jq -r '.[] | select(.categories[]? | test("cs\\.(AI|CL|LG)")) | .arxiv_id'

Recommended workflows#

Topic exploration#

"帮我找最近关于 agent memory 的论文":

1. deepxiv search "agent memory" --limit 5 --format json (add --date-from if "最近")
2. paper <id> --brief for each promising hit
3. Pick 1–2 for deeper reading

Single paper explanation#

"讲讲这篇论文 ":

1. paper <id> --brief
2. paper <id> --head
3. Read 1–2 sections most relevant to the question (or --preview if unsure)
4. Summarize, and say which rung you stopped at

Baseline / comparison table#

"帮我整理这个方向的 baseline":

1. Narrow search with --categories and optionally --min-citations
2. --brief every candidate
3. Read only Method / Experiments / Results for top picks
4. Extract: paper, task, dataset, metric, score, key idea

Author / project background check#

"这篇论文的作者还做过什么？" / "这个项目背景是什么？":

1. deepxiv wsearch "<author or project>" --json
2. If a related arXiv paper surfaces, climb the reading ladder on it
3. Optionally sc <id> for citation context

Citation-aware filtering#

"找有影响力的相关工作":

1. deepxiv search "..." --min-citations 100 --format json
2. Sort by citations via jq
3. Triage with --brief

Hot digest#

"本周热门论文":

1. deepxiv trending --days 7 --limit 10 --json
2. --brief the top picks
3. Optional --popularity to rank by attention
4. Compact digest: theme overview → one-line per paper → which to read deeper

See references/workflows.md for fuller versions of these.

Output rules#

• Always say which rung of the ladder informed your conclusion (e.g. "based on --brief only" vs. "after reading the Method section")
• Do not make section-level claims you didn't actually read
• Prefer concise bullet summaries when comparing multiple papers
• Keep context use low: small --limit, climb the ladder only as needed
• For literature reviews, prefer iterative narrowing over one giant search

Common failure modes#

Auth or rate-limit issues — run deepxiv health to check service reachability. If rate-limited or unauthorized, say so plainly and stop; do not silently retry.

Paper not found — verify ID format and source: arXiv ( 2409.05591), PMC ( PMC544940), Semantic Scholar ( 258001). If unsure which, try wsearch first.

Section name mismatch — section names are paper-specific. Run --head to list real section names before --section.

Over-reading — do not jump to full text when --brief, --preview, or one section would do.

Python 3.9 install — deepxiv may install via pip but crash on first run. Switch to a Python 3.10+ environment.

Good defaults#

• search --limit: 3–5 for triage, 10 max
• trending --limit: 5–10
• Section reads per paper: 1–2 unless asked otherwise
• Full paper reads: opt-in only
• agent query: only for genuinely open-ended multi-step research, with user consent