Use Papiers with agents

Papiers lets agents read your library from the terminal.

Claude Code, Codex, or any other agent that can run shell commands can search what you’ve saved and read documents, passages, highlights, notes, equations, and past conversations. They can read your library, but not modify it.

Ground agents in what you’ve read

A research agent usually starts with the prompt, the model’s prior knowledge, and whatever it can find on the web.

With Papiers, it can also start from your reading and thinking history.

Before proposing a hypothesis or experiment, an agent can search your library, read relevant papers, recover your highlights and notes, and revisit questions you’ve asked before. That gives your past judgment a way to shape what the agent explores next.

Highlights, annotations, notes, and conversations are especially useful because they record what caught your attention and what you thought about it. Saved-but-unread documents provide a weaker signal, but can still give the agent promising material to investigate.

The CLI includes a papiers-research skill that follows this pattern automatically: survey your recent reading, search the library for the task at hand, read relevant sources, then pull in your own notes and highlights before generating.

Install

The CLI is published as papiers on npm and requires Node.js 22 or newer.

npm install -g papiers
papiers version

Create a token

Open Settings → API tokens in Papiers and create a token.

Choose an expiration of 30, 60, or 90 days, or Never. Copy the token when it is created; it is only shown once.

Authenticate the CLI:

papiers auth login
# paste the token when prompted

papiers auth status

For agents and scripts, set the token directly:

export PAPIERS_TOKEN=...

Revoke a token from Settings or from the terminal:

papiers tokens list
papiers tokens revoke ID

Use the research skill

The npm package includes:

skills/papiers-research/SKILL.md

Point Claude Code, Codex, or another agent at the skill, or install it where that agent looks for skills.

The skill teaches the agent to distinguish between two kinds of signal in your library:

• Judgment — highlights, annotations, notes, and conversations from things you’ve actually read and thought about.
• Curation — things you saved but may not have read yet.

For research tasks, it looks at both, but gives more weight to the first.

Commands

Run the full reference with:

papiers --help --all

Search

Search uses the same index as Papiers itself.

papiers search "scaling laws for sparse attention" --limit 10 --json

A normal search can return matching documents together with evidence from passages, highlights, and equations, as well as standalone notes and conversations.

Narrow by type:

papiers search "contrastive loss" --kind passage --json
papiers search "rotary embeddings" --kind conversation --json
papiers search "L_{BND}" --kind equation --json

Search within one document:

papiers search "failure modes" --document-id doc_... --json

Project results into IDs when you want to pipe them into another command:

papiers search "mixture of experts" --passage-ids
papiers search "mixture of experts" --highlight-ids
papiers search "mixture of experts" --doc-ids

List

papiers list returns documents by default.

papiers list --limit 10 --json

List other kinds of items:

papiers list --kind highlight --since 30d --json
papiers list --kind note --json
papiers list --kind conversation --json

Or sort by recent activity:

papiers list \
  --order-by lastEngagedAt:desc \
  --limit 20 \
  --json

To find material you’ve saved but not meaningfully engaged with yet:

papiers list \
  --kind document \
  --filter engaged.eq=false \
  --json

Read

Every item has a stable ID. Pass it to papiers read to retrieve the underlying content.

papiers read pas_... --json
papiers read hl_... --json
papiers read nte_... --json

Read several items at once:

papiers read pas_... pas_... pas_... --json

For documents, select pages:

papiers read doc_... --pages 1,3-5 --json

Limit long reads when an agent only needs part of a source:

papiers read doc_... \
  --max-chars-per-item 4000 \
  --json

Use metadata-only output when you only need citation fields:

papiers read doc_... --format metadata --json

Or return text directly:

papiers read pas_... --format markdown
papiers read pas_... --format plain

Pipe commands together

The CLI is designed to compose with shell commands and agent tool calls.

For example, search for passages and read the matches:

papiers search "contrastive loss" --passage-ids \
  | papiers read @- --format plain --json

@- reads IDs from standard input.

Data commands return JSON by default. Pass --json when you also want errors returned as JSON instead of plain text.

Use --pretty when you are reading the output yourself.

IDs

IDs are typed by prefix:

The CLI also accepts papiers:// links copied from the app.

Filters

search and list accept structured filters:

--filter FIELD.OP=VALUE

For example:

papiers list \
  --filter publishedYear.gte=2024 \
  --filter annotated.eq=true \
  --json

Available fields include:

title
author
venue
doi
arxivId
publishedYear
publishedDate
sourceDomain
annotated
engaged

Operators include:

eq
in
contains
prefix
gte
gt
lte
lt
between

Keep structured attributes in filters rather than putting them into the search query:

papiers search "diffusion" \
  --filter venue.contains=neurips \
  --json

Up to 25 filters can be passed in one request.

Limits

The CLI is read-only. It cannot import, edit, highlight, tag, or publish.

--limit accepts values from 1 to 50. A single read returns up to 200,000 characters per item, and a request can contain up to 100 IDs.

Exit codes are:

0  success
1  failure
2  invalid usage

Table of contents · This page as Markdown