paperclip

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: paperclip
description: Search and read full-text biomedical papers, FDA/PMDA/EMA regulatory documents, clinical trial registries, and UniProt/PDB/ChEMBL entries with the Paperclip CLI from GXL. Covers installing and authenticating the `paperclip` binary with a PAPERCLIP_API_KEY, the read-only virtual filesystem under /papers, /fda, /trials, /proteins and /clipboard, source-scoped semantic search, corpus-wide grep, metadata lookup and SQL, map/reduce reading across many papers, figure vision analysis, opt-in paper repositories with claim verification, and line-pinned citations. Use when asked to install paperclip, run paperclip search/grep/map/reduce/sql/repo, find or read biomedical literature, regulatory filings or clinical trials through paperclip, or produce citations with line numbers.
allowed-tools: Bash Read Write
license: MIT
compatibility: Requires macOS or Linux with a POSIX shell and network access; the native installer does not support Windows (use the hosted MCP server there). Installs a self-contained CLI under ~/.paperclip — no Python environment of your own is needed. Authenticate with a PAPERCLIP_API_KEY exported from a .env file or the environment; browser OAuth is an interactive fallback the user must run. Verified against paperclip 0.7.14 and 0.7.15.
metadata:
  version: "1.2"
  skill-author: "K-Dense Inc."
  openclaw:
    primaryEnv: PAPERCLIP_API_KEY
    envVars:
      - name: PAPERCLIP_API_KEY
        required: false
        description: Paperclip API key from https://paperclip.gxl.ai/keys. Preferred over browser OAuth. Not required — the skill also covers installing the CLI and signing in interactively.
---

# Paperclip CLI

Paperclip exposes roughly 11M full-text papers, 217K+ regulatory documents, 110K+ clinical trial
protocols, and 574K+ protein entries as a **read-only virtual filesystem** navigated with Unix
commands, backed by server-side semantic search and LLM readers.

Every document is line-numbered, and that is the point of the tool: you cite `#L45` and a reader
jumps to the exact sentence. Read the lines you cite, do not paraphrase past what they say, and never
present a semantic-search snippet as if you had read the paper.

## Step 1 — preflight

Run this before anything else. It answers "is it installed" and "who am I" in one call.

```bash
command -v paperclip >/dev/null || echo "paperclip NOT INSTALLED"
command -v paperclip >/dev/null && { paperclip --version; [ -f .env ] && { set -a; . ./.env; set +a; }; paperclip config 2>&1 | grep -E "Auth|Health"; }
```

Read the `Auth:` line — it decides everything that follows:

| Output | Meaning | Do this |
|---|---|---|
| `✓ API key (env)` | The API key loaded. Correct state. | Proceed, using the auth prefix below |
| `✓ [email protected]` | **The key did not load** — this is stored OAuth, a different identity | If `.env` holds a key, you forgot the prefix. Fix it |
| `✗ (run: paperclip login)` | No credential at all | Ask the user to authenticate — see *Installing* |
| `paperclip NOT INSTALLED` | No binary | See *Installing* |

`Health: ✓ server reachable` is an **unauthenticated** probe, and `Auth: ✓` only means a credential is
*present*, not valid. A junk key produces the same two lines. Prove the credential with a real query:

```bash
[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip search -s pmc "test" -n 1
# invalid key → "[error] Authentication failed (API key invalid)." and exit 1
```

## Step 2 — operating rules

These are the rules that make the difference between working and silently-wrong. They matter more
than any individual command.

### 1. Put the auth prefix in *every* command

Shell state does not survive between tool calls. Exporting the key in one call and running
`paperclip` in the next means the key is **gone** — and Paperclip does not error, it silently falls
back to stored OAuth, i.e. a different identity and possibly a different account.

Prepend this to every invocation, in the directory holding `.env`: