/paperclip

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

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 | | `✓ someone@example.com` | **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:

[ -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`:

[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip <command>

The `[ -f .env ]` guard is required, not decoration: a bare `. ./.env` on a missing file **kills a POSIX shell**, so an unguarded prefix silently discards the rest of your command. Guarded, it is safe in all four states — `.env` present, `.env` absent, key already ambient, and under `sh` or `bash`. Skip the prefix only when preflight already reported `✓ API key (env)` without it.

Examples below omit the prefix for readability. Add it every time.

2. Never run an interactive command

These block on a prompt or a browser. Ask the user to run them and wait, or use the noted form:

| Command | Why | Instead | |---|---|---| | `paperclip login` | Opens a browser | Ask the user to run it, or use an API key | | `paperclip setup` | Includes `login` | Same | | `paperclip install` | Prompts for agent and path | `printf '1\n\n' \| paperclip install --dir <path>` (1 = Claude Code) | | `paperclip uninstall` | Confirmation prompt | Ask the user | | `paperclip fetch <url>` | Acts with the user's browser cookies | Only on explicit request |

With no TTY, an unauthenticated call exits cleanly (`[error] Not authenticated. Run: paperclip login`) rather than hanging — but do not rely on that; check preflight first.

3. Bound every output

`content.lines` runs to hundreds of long lines. Always pass `-n` to `search`, prefer `head -N`, section files, `grep`, and `scan` over `cat` on a full document, and pipe to `head` when unsure.

4. Capture result ids

`search`, `grep`, `filter`, and `map` all print an id that later commands consume. Capture it rather than re-reading it by eye:

Capture and use it in the *same* call, since the variable dies with the shell — prefix included here because this idiom is meant to be copied verbatim:

[ -f .env ] && { set -a; . ./.env; set +a; }
SID=$(paperclip search -s pmc "topic" -n 10 2>&1 | grep -oE 's_[a-f0-9]{8}' | head -1)
paperclip map --from "$SID" "