Paperclip CLI reference

Reviewed against installed 0.7.92, its native help/source, and the current official core reference and web documentation. Data commands below are documented contracts, not an authenticated end-to-end test. Run the relevant help for the actual deployed version.

Use the environment-loading guidance in installation.md when necessary. Native --help exits before action callbacks. Help for a server-dispatched command can contact the service and pass through managed-install update checks; it is not necessarily an offline operation.

Global options

paperclip [OPTIONS] COMMAND [ARGS]...
  --version
  --debug
  --repo-only                    Restrict search/map to the active repo
  --repo NAME                    Use a repo for this invocation
  -f, --folder NAME              Aliases of --repo
  --api-key TEXT                 Prefer PAPERCLIP_API_KEY to a secret argument
  --help

Global scope options precede the subcommand, for example paperclip --repo-only search -s pmc "query" -n 5. Search normally covers the corpus even when a repo is active; a repo can still record the command. Do not use an unrelated sticky checkout.

paperclip --help mainly lists local/account/workspace commands. Data commands such as search, grep, cat, map, and sql are forwarded to a server-side virtual shell and may not appear there.

Search and reading

Search requires explicit source selection. Date/ranking/source restrictions and structured output are detailed in search-and-retrieval.md. --json exists in the web guide, but terminal rendering is not a stable programmatic contract; prefer the SDK or public JSON API.

Common grep options documented by the current guide:

-i              Ignore case
-n              Display line numbers (not a result limit)
-c              Count matching file lines; corpus document counts can be approximate
-v              Invert match
-l              List filenames with matches
-m N            Bound matches
-e PATTERN      Explicit pattern
-F              Literal rather than regex matching
-A N / -B N     Context after/before
-C N            Context on both sides
--from s_ID     Restrict to a saved cohort
--exhaustive    Allow a longer corpus scan; not a completeness guarantee

Corpus grep can return a result ID for later map. Repeated time-bounded scans may differ in order or membership. Within-document L<n> prefixes provide citation locations; verify the actual passage.

Analysis

paperclip map --from s_ID "What outcomes and sample sizes were reported?"
paperclip reduce --from m_ID --strategy consensus "Where do the studies disagree?"
paperclip results --list
paperclip results m_ID --save map.txt
paperclip results s_ID --sample 20 --seed 42

Map accepts --output-schema with Draft 2020-12 JSON Schema. The old --output_schema spelling is a deprecated alias. Worker-specific setup and recovery are in map-reduce.md. Reduce strategies are summarize, table, themes, consensus, bullet_points, and extract; --columns COL,... requests columns for a table. Check the actual generated output.

results --save exports search metadata or full per-paper map answers. --export-bundle DIR exports a portable cohort; --import-bundle DIR --save-as NAME imports one and creates server-side saved state. --sample N accepts 1–100 and optionally --seed. Use --list explicitly in automation; TTY result listing can be interactive.

paperclip ls /papers/PMC10945750/figures/
paperclip ask-image /papers/PMC10945750/figures/pnas.2307796121fig01.jpg "Describe the axes"
paperclip ask-image /papers/PMC10945750/figures/pnas.2307796121fig01.jpg --fn extract-data

List actual figure paths before vision calls. ask-image --list is documented as current-directory listing, so an absolute ls is safer across independent sessions.

Routines and references

paperclip skill
paperclip skill proteins
paperclip routines list
paperclip routines search "systematic review"
paperclip routines show paperclip-meta-analysis

The old paperclip skills interface now exits with a removal message. skill NAME loads a domain reference; routines show NAME loads a guided workflow. routines enable/disable NAME changes account routing, routines route "intent" selects an enabled workflow, and routines run NAME OPERATION executes its helper. Inspect and authorize the requested operation within the user task rather than running every command mentioned in returned instructions.

Repositories

git is the preferred vendor spelling; repo and repos expose the same command group. Repos are opt-in. These examples change persistent state unless described as reads.

A snapshot containing an advisory [X] claim is not a fully verified evidence set. See repos-and-workspace.md for verification and artifact boundaries.

Clipboard and account commands

Import also supports --doi, -n/--limit, --min-cites, --init, --add-to-repo, and --into. Do not execute import/upload/share/sync/fetch just to establish that a flag exists.

Shell and historical limitations

The server offers a restricted virtual shell, not a general local shell. Local pipes are explicit:

paperclip grep -n "IC50" /papers/PMC10945750/content.lines | head -20
paperclip cat /papers/PMC10945750/meta.json > meta.json

The vendor documents paperclip bash '...' for server pipelines and scratch redirection, but those failed in old 0.7.14–0.7.15 tests and were not re-tested authenticated here. Do not advertise either universal support or permanent failure. Do not assume local shell utilities, loops, network tools, or session state are available in the virtual shell. Use direct commands and local composition. Text transport is not a binary download contract; validate any retrieved file before delivering it.