Deepxiv CLI

DeepXiv CLI Skill

🚀 30-Second Overview

What: Access open access academic papers (arXiv, PMC, bioRxiv, medRxiv) through a powerful CLI tool.

What you can do:

• 💬 Ask a question and get a cited answer, from arXiv or the web (deepxiv ask)
• 🔍 Search papers with semantic search
• 📄 Read papers section-by-section (save tokens!)
• 🧠 Use built-in AI agent for analysis
• 📊 Access biomedical literature (PMC)

When to use: User wants to search, read, or analyze academic papers

🎯 Command Selection Guide

I want to... → Use this command

📚 Core Commands Reference

0. Ask a Question (deepxiv ask)

When to use: The goal is an answer, not a specific paper's text. This runs the whole search → judge → read loop server-side and returns prose with real citations. Reach for it before hand-rolling search + paper --section.

# arXiv (default) — methods, numbers, experimental results
deepxiv ask "what speedup does speculative decoding report on HumanEval"
deepxiv ask "对比几种缓解 MoE 路由崩塌的方法" --effort high

# --web — current events, products, pricing, anything non-academic
deepxiv ask "Anthropic Claude API pricing tiers" --web
deepxiv ask "NeurIPS 2025 best paper winner" --web --search-type news
deepxiv ask "retrieval evaluation methodology" --web --search-type scholar

Requires a registered key. The auto-registered SDK token returns 403 — users must register at https://data.rag.ac.cn/register. Every account gets 300 agentic calls/day free, from a quota pool separate from the general daily limit (so a 429 here does not block search or paper). If a call 403s, tell the user to register rather than retrying.

Takes 8–30s end to end; the answer streams, so text appears well before that.

Writing the query — this matters more than any flag:

• Be specific. "what compression ratio does KV cache eviction report on LongBench" works; "kv cache" does not.
• Ask for numbers explicitly ("what speedup", "which benchmark") to make it read paper bodies rather than abstracts.
• Put scope in the query text: year, venue, category, author, min citations.
• Chinese queries work directly; the answer comes back in the query's language.
• If the answer misses, rephrase — don't just raise --effort. Effort adds reading rounds but cannot redirect first-round recall.

Reading the output:

• Answer → stdout; sources and progress → stderr. deepxiv ask "..." > answer.md captures only the answer.
• Every [arXiv:ID] is real — the service is instructed never to invent one, and says "no relevant papers" instead of fabricating. Keep those IDs in what you report back to the user.
• The sources list is the retrieval set, a superset of what's cited. The CLI shows only cited sources; --all-sources shows the rest.
• On --web, weigh evidence strength. The service reads only cached page bodies and never fetches live, so uncached pages contribute just a search snippet. The CLI marks pages read in full (📄) versus snippet-only (🔗), and the answer flags snippet-only claims. Pass that caveat on to the user instead of presenting everything as equally solid.
• On a truncation warning, do not treat the answer as complete — re-run with a larger --max-answer-tokens or a narrower query.
• Follow up on any cited paper with the normal commands: deepxiv paper <id> --section Method.

1. Search Papers (deepxiv search)

When to use: Finding relevant papers on a topic

# Basic search (quick)
deepxiv search "agent memory" --limit 5

# Advanced search with filters
deepxiv search "transformer" --format json
deepxiv search "LLM" --categories cs.AI,cs.CL --min-citations 100

# Date range
deepxiv search "vision models" --date-from 2024-01-01 --date-to 2024-12-31

Expected output: List of papers with title, arxiv_id, score, citation count Token cost: ≈500-1000 tokens per search Tips:

• Use --limit 3-5 for quick overview
• Use --format json for downstream processing
• Add --use-fine-rerank when ranking quality matters more than latency

2. Read arXiv Papers (deepxiv paper)

When to use: Understanding specific papers (choose format by depth needed)

Option A: Quick Summary (30 seconds)

deepxiv paper 2409.05591 --brief
# ✓ Best for: Quick understanding
# → Title, TLDR, keywords, citation count
# Token cost: ~500 tokens
# Use when: "What's this paper about?"

Option B: Paper Structure (2 minutes)

deepxiv paper 2409.05591 --head
# ✓ Best for: Understanding paper organization
# → Metadata, all sections with summaries
# Token cost: ~1-2k tokens
# Use when: "What does this paper contain?"

Option C: Quick Scan (3 minutes)

deepxiv paper 2409.05591 --preview
# ✓ Best for: Fast preview without full read
# → First ~10k characters
# Token cost: ~2k tokens
# Use when: "Let me scan the introduction"

Option D: Specific Section (1 minute)

deepxiv paper 2409.05591 --section Introduction
# ✓ Best for: Reading one section in detail
# → Full section content
# Token cost: ~1-5k tokens (varies by section)
# Use when: "I only need the introduction"

Option E: Complete Paper (for deep analysis)

deepxiv paper 2409.05591
# or explicitly: deepxiv paper 2409.05591 --raw
# ✓ Best for: Full text analysis
# → Complete paper in markdown
# Token cost: ~10-50k tokens
# Use when: "I need to thoroughly analyze this"

3. Access Biomedical Literature (deepxiv pmc)

When to use: Need medical, biology, or biomedical research

# Quick metadata
deepxiv pmc PMC544940 --head

# Full paper
deepxiv pmc PMC544940

Expected output: Paper metadata or complete paper JSON Token cost: ≈1-2k tokens (metadata), ≈10-30k tokens (full)

4. Manage Token (deepxiv token)

When to use: Check your API token status

deepxiv token
# Shows current token and daily limit info

Note: Token auto-registers on first use, saves to ~/.env

5. Find Researchers (deepxiv talent) — beta

Availability: ships in 1.1.0b1, source install only (pip install git+https://github.com/DeepXiv/deepxiv_sdk.git). The talent index is still being built out, so coverage is uneven — a search that returns thin or irrelevant people is a data gap, not a bad query.

When to use: You need people, not papers — who works on a topic, and what is their record

# Semantic search: describe the person you want in a sentence
deepxiv talent search "young faculty working on retrieval-augmented generation" --semantic --limit 5

# Keyword mode: matches names and affiliations
deepxiv talent search "Zhicheng Dou"

# Filter and sort
deepxiv talent search --tags LLM,Agent --career-stage student --sort total_citations --limit 10

# Full profile by ID (IDs come from search)
deepxiv talent survey 257                    # text summary
deepxiv talent survey 257 --format markdown  # the generated report
deepxiv talent survey 257 --no-refresh       # read-only, no Scholar refresh
deepxiv talent survey 257 --json             # raw JSON

Output: search gives id, names, affiliation, h-index, citations, tags. survey adds bio, education, work history, links, open-source projects, and publication metrics.

Quota: 1 agentic call each — the same pool as deepxiv ask (free 300/day). Requires a registered key. Profiles older than ~14 days refresh from Google Scholar automatically on survey; use --no-refresh to avoid that.

6. Intelligent Agent (deepxiv agent)

When to use: Need analysis beyond simple retrieval

# One-time query
deepxiv agent query "What are key innovations in this paper?"

# Multi-turn reasoning
deepxiv agent query "Compare these two approaches" --max-turn 10 --verbose

# First time setup
deepxiv agent config
# Configure your LLM (OpenAI, DeepSeek, OpenRouter, etc.)

Token cost: Varies by reasoning depth Requirements: Requires langgraph and langchain-core

🎬 Common Workflows

Workflow 1: Quick Paper Review (2 minutes)

# Step 1: Get brief info
deepxiv paper 2409.05591 --brief

# Step 2: Read introduction
deepxiv paper 2409.05591 --section Introduction

# Step 3: Check results (optional)
deepxiv paper 2409.05591 --section Results

Total tokens: ≈2-3k | Use case: Quick assessment before deciding to read fully

Workflow 2: Deep Paper Analysis (15 minutes)

# Step 1: Understand structure
deepxiv paper 2409.05591 --head

# Step 2: Read key sections
deepxiv paper 2409.05591 --section Introduction
deepxiv paper 2409.05591 --section Methods
deepxiv paper 2409.05591 --section Results

# Step 3: AI analysis
deepxiv agent query "Summarize the main contributions"

Total tokens: ≈10-15k | Use case: Thorough understanding

Workflow 3: Literature Search (5 minutes)

# Step 1: Find relevant papers
deepxiv search "agent memory" --limit 5

# Step 2: Quick assess each
for id in results; do
    deepxiv paper $id --brief
done

# Step 3: Deep read top 2
deepxiv paper <top_id_1>
deepxiv paper <top_id_2>

Total tokens: ≈5-10k | Use case: Literature review

💪 Capabilities & Limitations

What deepxiv Can Do ✅

What deepxiv Cannot Do ❌

🔧 Troubleshooting

Problem: Paper Not Found

deepxiv paper invalid_id
# Error: NotFoundError: Paper not found

Solution:

• Check arXiv ID format (should be like 2409.05591)
• Verify at https://arxiv.org

Problem: Daily Limit Exceeded

deepxiv search "topic"
# Error: RateLimitError: Daily limit reached

Solution:

• Wait until tomorrow (limit resets daily)
• OR email tommy@chien.io with name, email, phone for higher limit

Problem: Token Invalid

deepxiv paper 2409.05591
# Error: AuthenticationError: Invalid or expired token

Solution:

• Run deepxiv config --token YOUR_NEW_TOKEN
• Or delete ~/.env to auto-register new token

Problem: Agent Dependencies Missing

deepxiv agent query "analyze"
# Error: langgraph not installed

Solution:

pip install deepxiv-sdk[agent]

Problem: Timeout on Large Papers

deepxiv paper <large_paper_id>
# Error: Request timed out

Solution:

• Use --brief or --head instead of full paper
• Or use --section to read specific parts
• Increase timeout: Use Python API with Reader(timeout=180)

📊 Output Format Guide

For Search Results

Format: Show title, arxiv_id, brief context

1. Title of Paper (2409.05591)
   - Field: Computer Science / AI
   - Citations: 150
   - Key idea: Brief 1-line summary of main contribution

For Paper Reading

Always mention what command was used:

From `deepxiv paper 2409.05591 --brief`:
- Title: MemGPT: Towards LLMs as Operating Systems
- TLDR: Introduces hierarchical memory management for extended context
- Key concepts: agent memory, context management, LLM systems
- (~500 tokens)

For Structured Data

Use JSON format when:

• Processing results programmatically
• Building pipelines
• Storing for later analysis

deepxiv search "topic" --format json  # Pipe to other tools

⏱️ Token Budget Guide

When planning queries, consider token costs:

Quick Summary:        500 tokens
Metadata (--head):    1-2k tokens
One Section:          1-5k tokens (depends on section)
Full Paper:           10-50k tokens
Search Query:         0.5-1k tokens
Agent Analysis:       5-20k tokens (reasoning depth)

Recommendation: For general use, stick to --brief and --section to keep tokens under 5k per query.

🚀 Advanced Usage

Batch Processing (Multiple Papers)

for id in 2409.05591 2504.21776 2503.04975; do
    echo "=== $id ==="
    deepxiv paper $id --brief
done

Piping to Other Tools

deepxiv search "topic" --format json | jq '.results[] | .arxiv_id'

Custom Token Configuration

from deepxiv_sdk import Reader
reader = Reader(token="YOUR_TOKEN", timeout=120, max_retries=5)

🌐 Supported & Coming Soon

Current Support ✅

• arXiv - Computer Science, Physics, Math, Economics
• PMC - PubMed Central biomedical literature
• bioRxiv - Biology preprints (deepxiv search --biorxiv, deepxiv biorxiv DOI)
• medRxiv - Medicine preprints (deepxiv search --medrxiv, deepxiv medrxiv DOI)

Coming Soon 🔄

• Other OA - Additional open access sources
• Full OA Ecosystem - Unified cross-source search

📞 Getting Help

Command not working?

deepxiv <command> --help

Need a higher daily limit? Email: tommy@chien.io with name, email, phone

Found a bug? GitHub Issues

Learn more? Full Documentation

✨ Tips & Best Practices

1. Start with --brief - Always start with brief overview
2. Use sections - Don't load full papers when sections suffice
3. Save tokens - Stack operations to reduce API calls
4. Check limits - Run deepxiv token before large batches
5. Use agent wisely - For complex analysis that needs reasoning
6. Format choice - Use --format json for piping, plain text for humans
7. Error handling - Always handle "Paper not found" and "Limit exceeded" cases

Last Updated: 2024 | Version: 0.2.0 | Status: Production Ready