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:

• 🔍 Search papers with hybrid search (BM25 + Vector)
• 📄 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

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" --mode bm25 --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
• Adjust bm25_weight and vector_weight for different search styles

---

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. 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

Coming Soon 🔄

• bioRxiv - Biology preprints
• medRxiv - Medicine preprints
• 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