# 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`](https://www.npmjs.com/package/papiers) on npm and requires Node.js 22 or newer. ```sh 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: ```sh papiers auth login # paste the token when prompted papiers auth status ``` For agents and scripts, set the token directly: ```sh export PAPIERS_TOKEN=... ``` Revoke a token from Settings or from the terminal: ```sh papiers tokens list papiers tokens revoke ID ``` ## Use the research skill The npm package includes: ```text 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 | Command | What it does | | --- | --- | | `papiers search QUERY` | Search your library. | | `papiers list` | List documents, highlights, notes, conversations, equations, and other items. | | `papiers read ID [ID…]` | Read one or more items by ID. | | `papiers browse srch_…` | Continue through a saved set of search results. | | `papiers auth login\|status\|logout` | Manage authentication. | | `papiers tokens list\|revoke ID` | List or revoke API tokens. | | `papiers doctor` | Check the installation and connection. | | `papiers help [command]` | Show help for a command. | Run the full reference with: ```sh papiers --help --all ``` ## Search Search uses the same index as Papiers itself. ```sh 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: ```sh 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: ```sh papiers search "failure modes" --document-id doc_... --json ``` Project results into IDs when you want to pipe them into another command: ```sh 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. ```sh papiers list --limit 10 --json ``` List other kinds of items: ```sh papiers list --kind highlight --since 30d --json papiers list --kind note --json papiers list --kind conversation --json ``` Or sort by recent activity: ```sh papiers list \ --order-by lastEngagedAt:desc \ --limit 20 \ --json ``` To find material you’ve saved but not meaningfully engaged with yet: ```sh 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. ```sh papiers read pas_... --json papiers read hl_... --json papiers read nte_... --json ``` Read several items at once: ```sh papiers read pas_... pas_... pas_... --json ``` For documents, select pages: ```sh papiers read doc_... --pages 1,3-5 --json ``` Limit long reads when an agent only needs part of a source: ```sh papiers read doc_... \ --max-chars-per-item 4000 \ --json ``` Use metadata-only output when you only need citation fields: ```sh papiers read doc_... --format metadata --json ``` Or return text directly: ```sh 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: ```sh 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: | Prefix | Item | | --- | --- | | `doc_` | Document | | `pas_` | Passage | | `hl_` | Highlight | | `cnv_` | Conversation | | `eq_` | Equation | | `nte_` | Note | | `srch_` | Search result set | The CLI also accepts `papiers://` links copied from the app. ## Filters `search` and `list` accept structured filters: ```text --filter FIELD.OP=VALUE ``` For example: ```sh papiers list \ --filter publishedYear.gte=2024 \ --filter annotated.eq=true \ --json ``` Available fields include: ```text title author venue doi arxivId publishedYear publishedDate sourceDomain annotated engaged ``` Operators include: ```text eq in contains prefix gte gt lte lt between ``` Keep structured attributes in filters rather than putting them into the search query: ```sh 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: ```text 0 success 1 failure 2 invalid usage ``` Source: https://wiki.papiers.ai/docs/agents