Paperclip

# Search for papers
paperclip search "CRISPR base editing efficiency"

# Read a paper's metadata
paperclip cat /papers/bio_4f78753a6feb/meta.json

# Preview the first 50 lines
paperclip head -50 /papers/bio_4f78753a6feb/content.lines

# Grep within a single paper
paperclip grep -i "binding affinity" /papers/bio_4f78753a6feb/content.lines

# Grep across the entire corpus
paperclip grep -i "alphamissense" /papers/

# Map over search results with an AI reader
paperclip map --from s_abc123 "What methods were used?"

# Save results to a local file
paperclip search "CRISPR" -n 5 > results.txt

paperclip bash 'search "protein folding" | grep "deep learning"'

❯ Using /paperclip, find the relative frequency of methods which use Boltz
vs. Chai models in papers

● Skill(paperclip)
  ⎿  Successfully loaded skill

● I'll search for papers using both Boltz and Chai as structure prediction
  models, then dig into the methods sections.

● Bash(paperclip search "Boltz structure prediction" -n 50 --all 2>&1 | head -60)
  ⎿  Found 29 papers  [s_1cbc742e]

● Bash(paperclip search "Chai-1 structure prediction" -n 50 --all 2>&1 | head -60)
  ⎿  Found 20 papers  [s_0ef54807]

# In your terminal (while Claude Code is running)
paperclip search "GLP-1 receptor agonist efficacy" -n 5
paperclip map --from s_abc123 "What were the primary endpoints?"
paperclip grep -i "hazard ratio" /papers/med_84637b0c77f5/content.lines

paperclip search "protein structure prediction" -n 20
paperclip search -e "genome-wide association study"
paperclip search "cancer" --year 2024 --sort date
paperclip search --ranking vector "mechanisms of immune evasion in solid tumors"
paperclip search --ranking bm25 "TP53 R175H mutation"
paperclip search pmc --since 1y "gene therapy"
paperclip search --source biorxiv,pmc "gene therapy"
paperclip search -a "David Baker" -n 20
paperclip search -r "CRISPR.*Cas9"
paperclip search -c "CRISPR"
paperclip search -s fda "pembrolizumab"
paperclip search -s trials/us "phase 3 NSCLC"
paperclip search "semaglutide" /fda/us
paperclip search "breast cancer" /clinicaltrials/us

# Run three searches in parallel
paperclip searches "CRISPR delivery" "gene editing cancer" "viral vectors"

# Tag results for accumulation across calls
paperclip searches --quiet --tag crispr "CRISPR delivery" "gene editing cancer"

# All results accumulated into: s_abc123  [tag: crispr]  (58 unique papers)

paperclip lookup doi 10.1101/2024.01.15.575556
paperclip lookup author "David Baker" -n 10
paperclip lookup title "CRISPR base editing"
paperclip lookup pmc PMC7194329
paperclip lookup pmid 32943797
paperclip lookup arxiv 2403.03507
paperclip lookup journal "Nature Medicine"
paperclip lookup keywords "CRISPR"
paperclip lookup year 2024
paperclip lookup type review-article

# Corpus-wide regex search
paperclip grep -i "crispr\|cas9" /papers/

# Within a single paper
paperclip grep -i "binding" /papers/bio_4f78753a6feb/content.lines

# Show context lines
paperclip grep -i -C 2 "p53 mutation" /papers/bio_4f78753a6feb/content.lines

# Within a search result set
paperclip grep --from s_abc123 "kinase"

# Multiple patterns (OR'd together)
paperclip grep -e "CRISPR" -e "Cas9" /papers/bio_4f78753a6feb/content.lines

paperclip scan /papers/bio_4f78753a6feb/content.lines "AAV" "efficiency" "in vivo"
paperclip scan -i -C 3 /papers/bio_4f78753a6feb/content.lines "p53" "MDM2"

# Count papers by source
paperclip sql "SELECT source, COUNT(*) FROM documents GROUP BY source"

# Find papers by author
paperclip sql "SELECT title, doi, source FROM documents WHERE authors ILIKE '%Doudna%' LIMIT 5"

# Top journals (PMC papers)
paperclip sql "SELECT journal_title, COUNT(*) c FROM documents WHERE source = 'pmc' GROUP BY 1 ORDER BY c DESC LIMIT 10"

# Recent papers about a topic
paperclip sql "SELECT title, doi, pub_date FROM documents WHERE abstract_text ILIKE '%CRISPR%' ORDER BY pub_date DESC LIMIT 10"

paperclip export "SELECT title, doi, authors FROM documents WHERE source = 'biorxiv' ORDER BY created_at DESC LIMIT 100"

paperclip export --desc "CRISPR papers 2024" "SELECT DISTINCT d.title, d.doi FROM documents d JOIN content_blocks cb ON d.document_id = cb.document_id WHERE cb.content ILIKE '%CRISPR%' AND d.month_year >= '2024-01'"

# Step 1: search for papers
$ paperclip search "AAV gene therapy delivery" -n 3

Found 3 papers  [s_1907a2d0]

  1. Covalently linked adenovirus-AAV complexes as a novel
     platform technology for gene therapy
     Logan Thrasher Collins, Wandy Beatty, et al.
     bio_f402e4cf6e4a · bioRxiv · 2024-08-21

  2. Myocardial infarction creates a critical time window
     for AAV gene therapy
     Gonglie Chen, Yueyang Zhang, et al.
     bio_f2997a136fe7 · bioRxiv · 2024-06-10

  3. A facile chemical strategy to synthesize precise
     AAV-protein conjugates for targeted gene delivery
     Quan Pham, Jake Glicksman, et al.
     bio_ea44a956784e · bioRxiv · 2024-07-20

[197ms, saved to s_1907a2d0]

# Step 2: map over those results
$ paperclip map --from s_1907a2d0 \
    "What delivery vector was used and what transduction efficiency was reported?"

Map complete: 3/3 papers

  ✓ Covalently linked adenovirus-AAV complexes as a novel platform...
    The study used covalently linked adenovirus-AAV (Ad-AAV) complexes.
    In vitro, approximately 80% transduction in HEK293 cells.

  ✓ Myocardial infarction creates a critical time window for AAV...
    The study utilized AAV9. Transduction efficiency: 32.4 ± 4.5% at
    1 day post-MI vs 16.2 ± 3.1% in sham controls.

  ✓ A facile chemical strategy to synthesize precise AAV-protein...
    AAV2-HER2 conjugates for targeted delivery to HER2+ cancer cells.
    Explicit transduction efficiency percentages were not provided.

# Filter results — removes irrelevant papers
paperclip filter --from s_abc123 "AAV delivery to the lung"

# Require at least N papers to pass (exit code 1 if fewer survive)
paperclip filter --from s_abc123 --require 5 "AAV delivery to the lung"

# List available figures for a paper
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image --list'

# Describe a figure (default question)
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image fig1.tif'

# Ask a specific question about a figure
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image fig1.tif "What does this figure show?"'

# Analyze multiple figures
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image fig1.tif fig2.tif "Compare these"'

# First, list figures to see what's available
paperclip ls /papers/bio_4f78753a6feb/figures/

# Read metadata
paperclip cat /papers/bio_4f78753a6feb/meta.json

# Read full text (first 100 lines by default)
paperclip cat /papers/bio_4f78753a6feb/content.lines

# Read with line numbers
paperclip cat -n /papers/bio_4f78753a6feb/content.lines

# Read first N lines
paperclip cat --lines 50 /papers/bio_4f78753a6feb/content.lines

# Read a specific line range
paperclip cat --lines 100-200 /papers/bio_4f78753a6feb/content.lines

# Read a specific section
paperclip cat /papers/bio_4f78753a6feb/sections/Methods.lines

paperclip head -50 /papers/bio_4f78753a6feb/content.lines
paperclip tail -20 /papers/bio_4f78753a6feb/content.lines

# Short form (equivalent)
paperclip head -n 50 /papers/bio_4f78753a6feb/content.lines

paperclip ls /papers/bio_4f78753a6feb/
# meta.json  content.lines  sections/  figures/  supplements/

paperclip ls /papers/bio_4f78753a6feb/sections/
# Introduction.lines  Methods.lines  Results.lines  Discussion.lines

# Long format with token estimates
paperclip ls -l /papers/bio_4f78753a6feb/

paperclip tree /papers/bio_4f78753a6feb/
paperclip tree -L 2 /papers/bio_4f78753a6feb/

paperclip wc -l /papers/bio_4f78753a6feb/content.lines
#      847 /papers/bio_4f78753a6feb/content.lines

paperclip wc -w /papers/bio_4f78753a6feb/content.lines

# cd + command chain (cd only persists within the bash call)
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ls'
paperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image --list'
paperclip bash 'cd /papers/bio_4f78753a6feb/ && grep -i "kinase" content.lines'

# Sort, reverse, numeric, unique
paperclip bash 'grep "kinase" /papers/bio_abc123/content.lines | sort -u'

# Cut specific fields
paperclip bash 'grep "gene" /papers/bio_abc123/content.lines | cut -d: -f2'

# Translate characters
paperclip bash 'head -10 /papers/bio_abc123/content.lines | tr A-Z a-z'

# Extract lines 50-100
paperclip sed -n '50,100p' /papers/bio_4f78753a6feb/content.lines

# Substitution
paperclip bash 'head -20 /papers/bio_abc123/content.lines | sed "s/CRISPR/crispr/g"'

# Delete matching lines
paperclip bash 'cat /papers/bio_abc123/content.lines | sed "/^$/d"'

# Print Nth field
paperclip bash 'grep "kinase" /papers/bio_abc123/content.lines | awk "{print \$2}"'

# Custom delimiter
paperclip bash 'grep "kinase" /papers/bio_abc123/content.lines | awk -F: "{print \$1}"'

# Print matching lines (like grep)
paperclip bash 'cat /papers/bio_abc123/content.lines | awk "/kinase/"'

# Line range
paperclip bash 'cat /papers/bio_abc123/content.lines | awk "NR>=5 && NR<=10"'

paperclip bash 'cat /papers/bio_4f78753a6feb/meta.json | jq .title'
paperclip bash 'cat /papers/bio_4f78753a6feb/meta.json | jq keys'

# Count grep matches
paperclip bash 'grep -ic "p53" /papers/bio_4f78753a6feb/content.lines'

# Chain search → grep
paperclip bash 'search "CRISPR delivery" -n 10 | grep "AAV"'

# Write results to scratch space
paperclip bash 'grep -i "kinase" /papers/ > /.gxl/kinase_hits.txt'

# Multi-step pipeline
paperclip bash 'head -100 /papers/bio_abc123/content.lines | grep -i "method" | wc -l'

# Interactive picker (arrow keys to navigate, enter to save)
paperclip results

# View a specific result
paperclip results s_4a2b61f6

# View a map result
paperclip results m_ec2c9cc9

# Non-interactive list
paperclip results --list

# Export to CSV
paperclip results s_4a2b61f6 --save results.csv

# Export to plain text
paperclip results s_4a2b61f6 --save results.txt

# Save search results locally
paperclip search "CRISPR delivery" -n 10 > crispr_results.txt

# Save a paper's metadata
paperclip cat /papers/bio_4f78753a6feb/meta.json > meta.json

# Save SQL query output
paperclip sql "SELECT title, doi FROM documents WHERE authors ILIKE '%Doudna%' LIMIT 20" > doudna_papers.txt

# Append to an existing file
paperclip search "protein folding" >> research_log.txt

# Download a figure
paperclip cat /papers/bio_abc123/figures/fig1.tif > fig1.tif

paperclip login     # opens browser for sign-in (OAuth)
paperclip config    # check server URL + OAuth status (do not pass --api-key)
paperclip logout    # clear OAuth credentials and local config

export PAPERCLIP_API_KEY='gxl_...'
paperclip search "CRISPR delivery" -n 5

# Equivalent one-off:
paperclip --api-key 'gxl_...' search "CRISPR delivery" -n 5

# CI / production job
export PAPERCLIP_API_KEY="$SECRET"
paperclip search "gene therapy" -n 20

# Ad-hoc (avoid shell history: prefer env or a secret store)
paperclip --api-key "$PAPERCLIP_API_KEY" grep -i "AAV" /papers/

{
  "mcpServers": {
    "paperclip": {
      "url": "https://paperclip.gxl.ai/mcp",
      "type": "http",
      "headers": {
        "X-API-Key": "gxl_your_api_key_here"
      }
    }
  }
}

paperclip config                              # show current config
paperclip config --url http://localhost:8002   # set server URL (local dev)

# Via the CLI (interactive agent picker)
paperclip install

# Install to a specific project directory
paperclip install --dir /path/to/project

# Via npm/npx (no Python required)
npx gxl-paperclip
npx gxl-paperclip --all      # skip interactive prompt
npx gxl-paperclip --cursor   # Cursor only

paperclip update
# Current version: ...
# Checking for updates...
# ✓ Already up to date (v...)

meta.json        — title, authors, doi, date, abstract, journal (JSON)
content.lines    — full text, line-numbered: L<n>: <text>
sections/        — named section files (Introduction.lines, Methods.lines, …)
figures/         — figure files (PMC papers)
supplements/     — supplementary files (PMC papers)

export PAPERCLIP_API_KEY="pk_..."

from gxl_paperclip import PaperclipClient, APIKeyAuth

client = PaperclipClient.from_env()              # reads PAPERCLIP_API_KEY
# — or pass an explicit strategy —
client = PaperclipClient(auth=APIKeyAuth("pk_..."))

from gxl_paperclip import PaperclipClient

client = PaperclipClient.from_env()

result = client.search("CRISPR lipid nanoparticle", limit=5, source="pmc")
print(result.output)        # same formatted text the CLI prints
print(result.result_id)     # e.g. "s_14bebc10" — pass to map_()

for event in client.map_("What delivery methods were used?", from_results=result.result_id):
    if event.type == "progress":
        print(f"{event.completed}/{event.total} papers done")
    else:
        print(event.output)

client.search(
    query: str,
    *,
    limit: int | None = None,
    source: str | None = None,
    exact: bool = False,
    since: str | None = None,
    sort: str | None = None,
    author: str | None = None,
    journal: str | None = None,
    year: int | str | None = None,
    type: str | None = None,
    category: str | None = None,
    mode: str | None = None,
    all: bool = False,
    timeout: float | None = None,
) -> ExecuteResult

client.lookup(
    field: str,
    value: str,
    *,
    limit: int | None = None,
    timeout: float | None = None,
) -> ExecuteResult

client.sql(
    query: str,
    *,
    source: str | None = None,
    timeout: float | None = None,
) -> ExecuteResult

client.map_(
    question: str,
    *,
    from_results: str,
    timeout: float | None = None,
) -> Iterator[MapEvent]

client.pull(
    target: str,
    dest: str | None = None,
    *,
    timeout: float | None = None,
) -> ExecuteResult

client.ask_image(
    path: str,
    question: str | None = None,
    *,
    fn: str | None = None,
    timeout: float | None = None,
) -> ExecuteResult

client.bash(
    script: str,
    *,
    timeout: float | None = None,
) -> ExecuteResult

result = client.bash('search "protein folding" | grep -i "deep learning"')

client.results.list(*, limit: int | None = None) -> list[ResultRow]
client.results.get(result_id: str) -> ResultData

client.papers.cat(path)
client.papers.head(path, *, lines=None)      # default 10 lines (server default)
client.papers.tail(path, *, lines=None)      # default 10 lines (server default)
client.papers.ls(path)
client.papers.grep(pattern, path, *, ignore_case=False, extended=False)
client.papers.scan(path, patterns)           # list of patterns OR'd together

client.execute(command: str, args: Sequence[str] | None = None, *, timeout=None) -> ExecuteResult
client.stream(command: str, args: Sequence[str] | None = None, *, timeout=None) -> Iterator[MapEvent]

result = client.execute(
    "awk",
    ["-F", "\t", "{print $1}", "/papers/PMC1/content.lines"],
)

from gxl_paperclip import (
    AuthError, RateLimitError, NotFoundError, ServerError,
    RequestTimeoutError, NetworkError,
)

try:
    client.search("AlphaFold")
except AuthError:
    ...  # invalid API key or expired credentials
except RateLimitError:
    ...  # HTTP 429
except RequestTimeoutError:
    ...  # client-side timeout
except ServerError as exc:
    print(exc.status_code, exc.body)