Documentation

# Search for paperspaperclip search "CRISPR base editing efficiency" # Read a paper's metadatapaperclip cat /papers/bio_4f78753a6feb/meta.json # Preview the first 50 linespaperclip head -50 /papers/bio_4f78753a6feb/content.lines # Grep within a single paperpaperclip grep -i "binding affinity" /papers/bio_4f78753a6feb/content.lines # Grep across the entire corpuspaperclip grep -i "alphamissense" /papers/ # Map over search results with an AI readerpaperclip map --from s_abc123 "What methods were used?" # Save results to a local filepaperclip search "CRISPR" -n 5 > results.txt

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

❯ Using /paperclip, find the relative frequency of methods which use Boltzvs. 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 5paperclip 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 20paperclip search -e "genome-wide association study"paperclip search "cancer" --year 2024 --sort datepaperclip 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 20paperclip search -r "CRISPR.*Cas9"paperclip search -c "CRISPR"paperclip search -s fda "pembrolizumab"paperclip search -s trials/us "phase 3 NSCLC"paperclip search -s patents "covalent KRAS inhibitor"paperclip search "semaglutide" /fda/uspaperclip search "breast cancer" /clinicaltrials/us

# Run three searches in parallelpaperclip searches "CRISPR delivery" "gene editing cancer" "viral vectors" # Tag results for accumulation across callspaperclip 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.575556paperclip lookup author "David Baker" -n 10paperclip lookup title "CRISPR base editing"paperclip lookup pmc PMC7194329paperclip lookup pmid 32943797paperclip lookup arxiv 2403.03507paperclip lookup journal "Nature Medicine"paperclip lookup keywords "CRISPR"paperclip lookup year 2024paperclip lookup type review-article

# Corpus-wide regex searchpaperclip grep -i "crispr\|cas9" /papers/ # Within a single paperpaperclip grep -i "binding" /papers/bio_4f78753a6feb/content.lines # Show context linespaperclip grep -i -C 2 "p53 mutation" /papers/bio_4f78753a6feb/content.lines # Within a search result setpaperclip 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 sourcepaperclip sql "SELECT source, COUNT(*) FROM documents GROUP BY source" # Find papers by authorpaperclip 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 topicpaperclip 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.

paperclip map --from s_1907a2d0 \  --output-schema '{"type":"object","required":["effect"],"additionalProperties":false,"properties":{"effect":{"type":["number","null"]}}}' \  "Extract the reported effect. Use null when it is not reported."

# Synthesize a map into prosepaperclip reduce --from m_def456 "Compare the delivery vectors and efficiencies" # Produce a structured comparison tablepaperclip reduce --from m_def456 --strategy table \    --columns "vector,cell type,efficiency" "Compare delivery across papers" # Omit --from to reduce the most recent mappaperclip reduce "Summarize the consensus across these papers"

# Filter results — removes irrelevant paperspaperclip 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 paperpaperclip 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 figurepaperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image fig1.tif "What does this figure show?"' # Analyze multiple figurespaperclip bash 'cd /papers/bio_4f78753a6feb/ && ask_image fig1.tif fig2.tif "Compare these"' # First, list figures to see what's availablepaperclip ls /papers/bio_4f78753a6feb/figures/

# Discover routines available to this accountpaperclip routines listpaperclip routines search "systematic review" # Inspect and enable a routinepaperclip routines show paperclip-meta-analysispaperclip routines enable paperclip-meta-analysis # Load the enabled routine matching an agent's current taskpaperclip routines route "meta-analysis of CAR-T efficacy" # Run a trusted helper requested by the routinepaperclip routines run paperclip-meta-analysis status --dir ./car-t-analysis --json # Turn off account-level routing for a routinepaperclip routines disable paperclip-meta-analysis

# Read metadatapaperclip cat /papers/bio_4f78753a6feb/meta.json # Read full text (first 100 lines by default)paperclip cat /papers/bio_4f78753a6feb/content.lines # Read with line numberspaperclip cat -n /papers/bio_4f78753a6feb/content.lines # Read first N linespaperclip cat --lines 50 /papers/bio_4f78753a6feb/content.lines # Read a specific line rangepaperclip cat --lines 100-200 /papers/bio_4f78753a6feb/content.lines # Read a specific sectionpaperclip cat /papers/bio_4f78753a6feb/sections/Methods.lines

paperclip head -50 /papers/bio_4f78753a6feb/content.linespaperclip 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 estimatespaperclip 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, uniquepaperclip bash 'grep "kinase" /papers/bio_abc123/content.lines | sort -u' # Cut specific fieldspaperclip bash 'grep "gene" /papers/bio_abc123/content.lines | cut -d: -f2' # Translate characterspaperclip bash 'head -10 /papers/bio_abc123/content.lines | tr A-Z a-z'

# Extract lines 50-100paperclip sed -n '50,100p' /papers/bio_4f78753a6feb/content.lines # Substitutionpaperclip bash 'head -20 /papers/bio_abc123/content.lines | sed "s/CRISPR/crispr/g"' # Delete matching linespaperclip bash 'cat /papers/bio_abc123/content.lines | sed "/^$/d"'

# Print Nth fieldpaperclip bash 'grep "kinase" /papers/bio_abc123/content.lines | awk "{print \$2}"' # Custom delimiterpaperclip 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 rangepaperclip 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 matchespaperclip bash 'grep -ic "p53" /papers/bio_4f78753a6feb/content.lines' # Chain search → greppaperclip bash 'search "CRISPR delivery" -n 10 | grep "AAV"' # Write results to scratch spacepaperclip bash 'grep -i "kinase" /papers/ > /.gxl/kinase_hits.txt' # Multi-step pipelinepaperclip 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 resultpaperclip results s_4a2b61f6 # View a map resultpaperclip results m_ec2c9cc9 # Non-interactive listpaperclip results --list # Export to CSVpaperclip results s_4a2b61f6 --save results.csv # Export to plain textpaperclip results s_4a2b61f6 --save results.txt

# Save search results locallypaperclip search "CRISPR delivery" -n 10 > crispr_results.txt # Save a paper's metadatapaperclip cat /papers/bio_4f78753a6feb/meta.json > meta.json # Save SQL query outputpaperclip sql "SELECT title, doi FROM documents WHERE authors ILIKE '%Doudna%' LIMIT 20" > doudna_papers.txt # Append to an existing filepaperclip search "protein folding" >> research_log.txt # Download a figurepaperclip cat /papers/bio_abc123/figures/fig1.tif > fig1.tif

# 1. Create (or switch into) a repo — it becomes the active, sticky repopaperclip git init kras-resistance "KRAS G12C resistance mechanisms" # 2. Search is auto-scoped to the repo; add papers with a verifiable claimpaperclip search "KRAS G12C adagrasib resistance" -n 10paperclip git add PMC10150846 "Adagrasib ORR 42.9% in NSCLC" --lines L210-L214 # 3. Commit — every unverified claim is checked against the full source textpaperclip git commit -m "first-line resistance papers" # 4. Explore a side question on a branch, then fold it back inpaperclip git branch safety-signalspaperclip git add PMC8834120 "Grade 3+ hepatotoxicity in 5.2%" --lines L88paperclip git commit -m "hepatotoxicity signals"paperclip git checkout mainpaperclip git merge safety-signals # 5. Audit and exportpaperclip git logpaperclip git export bibtex -o kras.bib

paperclip git init kras-resistance "KRAS G12C resistance mechanisms"paperclip git init my-reviewpaperclip git init lit-review --from-library            # seed with all matched library paperspaperclip git init subset --from-library -s "CRISPR"    # seed with matching library papers

paperclip git                  # list 10 most recent repos (active first)paperclip git -n 0             # list all repospaperclip git info kras-resistance   # papers, branches, and commit history for one repo

paperclip git checkout kras-resistance   # activate a repo (sticky)paperclip git checkout main              # switch to a branch (when the name matches a branch)paperclip git checkout -                 # deactivate — commands run against the full corpus againpaperclip git switch main                # also accepted; same as checkout

paperclip git add PMC123 bio_456paperclip git add PMC123 "Hypertonic saline reduces cold duration by 1.9 days"paperclip git add PMC123 "Saline shortens URTI by 1.5 days" --lines L45-L52paperclip git add PMC123 "ORR 32.4%" --commit "ADC efficacy"   # add then commitpaperclip git add --from-library                                # add matched library paperspaperclip git add --from-library -s "proteomics"

paperclip git remove PMC8834120paperclip git remove 4402004380   # e.g. dropping a predatory-journal hit during screening

paperclip git commit -m "initial resistance papers"paperclip git commit -m "Found 3 phase-2 trials" -r "Added spleen LNP data, still need phase-3."paperclip git commit -m "quick snapshot" --no-verify

paperclip git status # ○ = claim not yet verified (run: paperclip git commit -m "…")# ✓ = claim supported by source   ✗ = claim not supported

paperclip git logpaperclip git log -n 5paperclip git log --branch safety-concernspaperclip git log --json

paperclip git historypaperclip git history -t search_papers   # filter by tool namepaperclip git history -n 10              # results per pagepaperclip git history --json

paperclip git branch                   # list branches (active marked)paperclip git branch clinical-data     # create + switch to a new branch

paperclip git checkout mainpaperclip git merge clinical-data

paperclip git export bibtex > kras.bibpaperclip git export bib -o kras.bib       # "bib" is an alias for bibtexpaperclip git export ris -o kras.rispaperclip git export markdown -o review.md  # "md" is an alias for markdownpaperclip git export csv -o papers.csv

paperclip git citations                          # counts for all repo paperspaperclip git citations --refresh                # force a fresh lookup from Semantic Scholarpaperclip git citations --graph                  # citation relationships between repo paperspaperclip git citations PMC9170150 PMC11748609   # specific papers

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 jobexport 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"      }    }  }}

curl -sS -X POST https://paperclip.gxl.ai/api/v1/search \  -H "Content-Type: application/json" \  -H "X-API-Key: $PAPERCLIP_API_KEY" \  -d '{    "query": "Allgrove syndrome",    "ranking": "bm25",    "num_results": 50,    "filters": { "max_year": 2016 }  }'

curl -sS -X POST https://paperclip.gxl.ai/api/v1/lookup \  -H "Content-Type: application/json" \  -H "X-API-Key: $PAPERCLIP_API_KEY" \  -d '{ "pmid": "27048983" }' curl -sS https://paperclip.gxl.ai/api/v1/documents/pmid:27048983 \  -H "X-API-Key: $PAPERCLIP_API_KEY"

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

# Via the CLI (interactive agent picker)paperclip install # Install to a specific project directorypaperclip install --dir /path/to/project # Via npm/npx (no Python required)npx gxl-paperclipnpx gxl-paperclip --all      # skip interactive promptnpx gxl-paperclip --cursor   # Cursor only

# Discover and enable guided workflowspaperclip routines listpaperclip routines search "systematic review"paperclip routines enable paperclip-meta-analysis # Load an enabled routine when its trigger matchespaperclip routines route "meta-analysis"paperclip routines show paperclip-meta-analysis

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

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)

# Upload a folder of PDFs (recursive)paperclip cp ~/my_papers/ # Upload a single PDFpaperclip cp paper.pdf # Upload into a specific clipboard folderpaperclip cp ~/data/ /clipboard/research/

# Link a corpus paper (also works for /fda/ and /trials/)paperclip cp /papers/PMC7194329 /clipboard/my-review/ # Link an existing clipboard doc into another folderpaperclip cp /clipboard/usr_c1f9c5eac891 /clipboard/archive/

# Download via your Chrome session and add to clipboardpaperclip fetch https://www.nature.com/articles/s41586-023-05724-2paperclip fetch 10.1038/s41586-023-05724-2 --into /clipboard/my-review/ # Import a .bib/.ris — each citation becomes a folder# (corpus link when found, else citation metadata)paperclip import refs.bib --into /clipboard/thesis-refs/

paperclip upload analysis.json report.html --into analyses/my-topic

# List folders / documentspaperclip ls /clipboard/paperclip ls /clipboard/my_papers/ # Recursive listingpaperclip tree /clipboard/ # Read a documentpaperclip head -20 /clipboard/my_papers/usr_c1f9c5eac891/content.linespaperclip cat /clipboard/my_papers/usr_c1f9c5eac891/meta.json

# Create a folder (nesting allowed)paperclip mkdir /clipboard/oncology/ # Move or rename a folder or documentpaperclip mv /clipboard/my_papers /clipboard/oncology/paperclip mv /clipboard/a/usr_abc /clipboard/a/renamed.pdf # Storage summary, find files, countspaperclip du /clipboard/paperclip find "*.pdf" /clipboard/

# Keyword search across the whole clipboardpaperclip search -s clipboard "deep learning" # Scope the search to one folderpaperclip search -s clipboard/my-review "dose escalation" # Full-text regex over clipboard docspaperclip grep "methods" /clipboard/paperclip grep "results" /clipboard/my_papers/usr_c1f9c5eac891/content.lines # Query your clipboard AND the public corpus, then mergepaperclip search -s pmc,clipboard "CRISPR base editing"

paperclip ask-image /clipboard/my_papers/usr_c1f9c5eac891/figures/figure_1.png "What does this figure show?"

# Share a folder (default role: viewer)paperclip share my_papers bob@company.com # Grant edit accesspaperclip share my_papers bob@company.com --role editor # Revoke accesspaperclip unshare my_papers bob@company.com

# Register a local folder (optionally name the remote prefix)paperclip sync add ~/papers --prefix oncology # Sync: upload new/modified, prune deleted (preview with --dry-run)paperclip sync runpaperclip sync run --dry-run # One-shot upload without registeringpaperclip sync upload ~/my_papers/ # Status and cleanuppaperclip sync statuspaperclip sync rm oncology        # or a usr_ id, or --all

# Delete a folderpaperclip rm /clipboard/my_papers -R # Delete a single documentpaperclip rm /clipboard/usr_c1f9c5eac891 # Delete everythingpaperclip rm /clipboard -R

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 printsprint(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) -> ExecuteResultclient.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 credentialsexcept RateLimitError:    ...  # HTTP 429except RequestTimeoutError:    ...  # client-side timeoutexcept ServerError as exc:    print(exc.status_code, exc.body)