v0.2.0
OpenAPI 3.1.0
Paperpile CLI
The paperpile-stage CLI gives scripts and agents the same library access as the API, as a single self-contained binary.
Quick start (Collapsed)
Install the CLI, sign in once, and list the five references you added last:
curl -fsSL https://cli.paperpile.com/install.sh | sh -s -- --channel staging
paperpile-stage auth login
paperpile-stage references list --sort date_added --order desc --limit 5
Install (Collapsed)
curl -fsSL https://cli.paperpile.com/install.sh | sh -s -- --channel staging
Windows (PowerShell):
& ([scriptblock]::Create((irm https://cli.paperpile.com/install.ps1))) -Channel staging
The script verifies checksums and installs to /usr/local/bin (or ~/.local/bin). Later, paperpile-stage update gets you
the newest version.
Authentication (Collapsed)
paperpile-stage auth login opens a browser and stores the credential locally. To skip the browser:
| Method | Use it for |
|---|---|
paperpile-stage auth login --with-key |
Paste an API key once |
PAPERPILE_API_KEY environment variable |
CI and agents |
API keys come from your Paperpile account settings — the same tokens work for the REST API and MCP.
Output (Collapsed)
On a terminal, results render as tables. Piped, the same command emits JSON on stdout, so
paperpile-stage references list | jq just works. Errors are a single JSON line on stderr, and the exit code tells you what
went wrong:
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Generic failure |
2 |
Usage error |
3 |
Not authenticated |
4 |
Forbidden |
5 |
Not found |
6 |
Rate limited |
7 |
Network problem |
130 |
Interrupted |
The command reference below is generated from the CLI itself; paperpile-stage --help shows the same thing offline.
Global flags (Collapsed)
These work with every paperpile-stage command:
| Flag | Description |
|---|---|
--agent |
Force JSON output |
--human |
Force human-readable output |
auth login (Collapsed)
Sign in through a browser, or store a key you paste
paperpile-stage auth login [flags]
| Flag | Description |
|---|---|
--with-key |
Store a key you paste instead of opening a browser |
-q, --quiet |
Suppress progress messages |
--no-input |
Never prompt; fail instead |
Examples
# Sign in through your browser
paperpile-stage auth login
# Paste an API key instead of opening a browser
paperpile-stage auth login --with-key
auth logout (Collapsed)
Remove the stored credential (locally)
paperpile-stage auth logout [flags]
Examples
# Remove the credential stored on this machine
paperpile-stage auth logout
auth status (Collapsed)
Show the authenticated account
paperpile-stage auth status [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
Examples
# Show which account you are signed in as
paperpile-stage auth status
# Check an API key without storing it
paperpile-stage auth status --api-key "$PAPERPILE_API_KEY"
libraries list (Collapsed)
List the libraries you can reach
paperpile-stage libraries list [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
Examples
# List the libraries you can use
paperpile-stage libraries list
# Get the same list as JSON, for a script
paperpile-stage libraries list --agent
references list (Collapsed)
List and filter references
paperpile-stage references list [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--query <value> |
Search terms; supports title:, author:, "phrases" and not: |
--folder <value> |
Folder id — filters a list, destination when saving; repeatable |
--label <value> |
Label id — filters a list, applied when saving; repeatable |
--type <value> |
Only references of this type; repeatable |
--starred |
Starred only when listing; sets starred when updating |
--has-pdf |
Only references with a primary PDF |
--trashed-mode <value> |
exclude (default), only, or include |
--sort <value> |
date_added, date_published, title, first_author, journal or relevance |
--order <value> |
asc or desc |
--limit <value> |
Results per page, 1-100 (default 50) |
--cursor <value> |
Cursor from a previous page |
--all |
Follow the cursor until every page is read |
--fields <value> |
Return only these fields; repeatable |
--expand <value> |
Replace ids with the objects they point at; repeatable |
Examples
# Search by author and phrase, newest first
paperpile-stage references list --query 'author:smith "deep learning"' --sort date_published --order desc
# Every starred reference with a PDF in one folder
paperpile-stage references list --folder <folder-id> --starred --has-pdf --all
references get (Collapsed)
Show one reference
paperpile-stage references get <reference-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
Examples
# Show one reference
paperpile-stage references get <reference-id>
# Show a reference from a shared library
paperpile-stage references get <reference-id> --library <library-id>
references add (Collapsed)
Save references from DOIs, a BibTeX file, or JSON
paperpile-stage references add [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--doi <value> |
DOI to resolve and save; repeatable |
--bibtex <value> |
BibTeX file to import, or - for stdin |
--json <value> |
Read the request body from a JSON file, or - for stdin |
--folder <value> |
Folder id — filters a list, destination when saving; repeatable |
--label <value> |
Label id — filters a list, applied when saving; repeatable |
--note <value> |
Note text |
--no-find-pdfs |
Do not queue a PDF crawl for what is saved |
--allow-duplicates |
Save even when the identifier is already in the library |
Examples
# Save two papers by DOI and label them
paperpile-stage references add --doi 10.1038/nature12373 --doi 10.1126/science.1225829 --label <label-id>
# Import a BibTeX file into a folder
paperpile-stage references add --bibtex library.bib --folder <folder-id>
references update (Collapsed)
Change references, or file them into folders and labels
paperpile-stage references update <reference-id…> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--json <value> |
Read the request body from a JSON file, or - for stdin |
--title <value> |
Reference title |
--starred |
Starred only when listing; sets starred when updating |
--not-starred |
Clear the star |
--trashed |
Move to trash |
--not-trashed |
Restore from trash |
--note <value> |
Note text |
--add-folder <value> |
File into this folder; repeatable |
--remove-folder <value> |
Remove from this folder; repeatable |
--add-label <value> |
Apply this label; repeatable |
--remove-label <value> |
Remove this label; repeatable |
Examples
# Correct the title of one reference
paperpile-stage references update <reference-id> --title 'Attention is all you need'
# Star two references and file them into a folder
paperpile-stage references update <reference-id> <reference-id> --starred --add-folder <folder-id>
references delete (Collapsed)
Permanently delete references
paperpile-stage references delete <reference-id…> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--yes |
Skip the confirmation prompt |
--no-input |
Never prompt; fail instead |
Examples
# Delete a reference without the confirmation prompt
paperpile-stage references delete <reference-id> --yes
folders list (Collapsed)
List folders
paperpile-stage folders list [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--parent <value> |
Parent folder id, or none for the top level |
--fields <value> |
Return only these fields; repeatable |
--expand <value> |
Replace ids with the objects they point at; repeatable |
Examples
# List every folder
paperpile-stage folders list
# List the subfolders of one folder
paperpile-stage folders list --parent <folder-id>
folders create (Collapsed)
Create a folder
paperpile-stage folders create [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--name <value> |
Name |
--parent <value> |
Parent folder id, or none for the top level |
Examples
# Create a top-level folder
paperpile-stage folders create --name 'Reading group'
# Create a subfolder
paperpile-stage folders create --name 2024 --parent <folder-id>
folders update (Collapsed)
Rename a folder or move it
paperpile-stage folders update <folder-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--name <value> |
Name |
--parent <value> |
Parent folder id, or none for the top level |
Examples
# Rename a folder
paperpile-stage folders update <folder-id> --name 'Reading group (archive)'
# Move a folder to the top level
paperpile-stage folders update <folder-id> --parent none
folders delete (Collapsed)
Delete a folder
paperpile-stage folders delete <folder-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--trash-references |
Also move the references inside it to trash |
--yes |
Skip the confirmation prompt |
--no-input |
Never prompt; fail instead |
Examples
# Delete a folder and move its references to the trash
paperpile-stage folders delete <folder-id> --trash-references --yes
labels list (Collapsed)
List labels
paperpile-stage labels list [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--fields <value> |
Return only these fields; repeatable |
Examples
# List every label
paperpile-stage labels list
labels create (Collapsed)
Create a label
paperpile-stage labels create [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--name <value> |
Name |
--color <value> |
Label color, style_0 to style_24 |
Examples
# Create a label
paperpile-stage labels create --name 'To read' --color style_3
labels update (Collapsed)
Rename a label or change its color
paperpile-stage labels update <label-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--name <value> |
Name |
--color <value> |
Label color, style_0 to style_24 |
Examples
# Rename a label
paperpile-stage labels update <label-id> --name Read
# Change its color
paperpile-stage labels update <label-id> --color style_7
labels delete (Collapsed)
Delete a label
paperpile-stage labels delete <label-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--trash-references |
Also move the references inside it to trash |
--yes |
Skip the confirmation prompt |
--no-input |
Never prompt; fail instead |
Examples
# Delete a label and keep its references
paperpile-stage labels delete <label-id> --yes
files list (Collapsed)
List files
paperpile-stage files list [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--reference <value> |
Only files attached to this reference |
--fields <value> |
Return only these fields; repeatable |
--expand <value> |
Replace ids with the objects they point at; repeatable |
Examples
# List the files attached to one reference
paperpile-stage files list --reference <reference-id>
# List every file in the library
paperpile-stage files list
files upload (Collapsed)
Upload a file to a reference
paperpile-stage files upload <path> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--reference-id <value> |
Reference by id; repeatable when downloading |
--filename <value> |
Store the upload under this name |
--primary |
Make this the reference’s main PDF |
Examples
# Attach a PDF and make it the main one
paperpile-stage files upload paper.pdf --reference-id <reference-id> --primary
# Attach a data file under a clearer name
paperpile-stage files upload data.xlsx --reference-id <reference-id> --filename supplementary-data.xlsx
files delete (Collapsed)
Permanently delete a file
paperpile-stage files delete <file-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--yes |
Skip the confirmation prompt |
--no-input |
Never prompt; fail instead |
Examples
# Delete a file without the confirmation prompt
paperpile-stage files delete <file-id> --yes
files content (Collapsed)
Download one file as-is
paperpile-stage files content <file-id> [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--to <value> |
Directory to write into (default: the current directory) |
--output <value> |
Write the file here, or - for stdout |
Examples
# Save a file under a name you choose
paperpile-stage files content <file-id> --output paper.pdf
# Save it into a directory under its own name
paperpile-stage files content <file-id> --to ./downloads
files download (Collapsed)
Save references' PDFs, markdown and BibTeX
paperpile-stage files download [flags]
| Flag | Description |
|---|---|
--api-key <value> |
Use this key for one command |
--library <value> |
Library to work in (default: your personal library) |
--citekey <value> |
Reference by citekey; repeatable |
--reference-id <value> |
Reference by id; repeatable when downloading |
--to <value> |
Directory to write into (default: the current directory) |
--no-markdown |
Skip the extracted paper.md |
--no-bibtex |
Skip reference.bib |
--supplementary |
Include the non-primary attachments |
-q, --quiet |
Suppress progress messages |
Examples
# Save a paper's PDF, markdown and BibTeX by citekey
paperpile-stage files download --citekey smith2020 --to ./papers
# Save only the PDFs of two references, attachments included
paperpile-stage files download --reference-id <reference-id> --reference-id <reference-id> --no-markdown --no-bibtex --supplementary
update (Collapsed)
Update this binary to the published version
paperpile-stage update [version] [flags]
| Flag | Description |
|---|---|
-q, --quiet |
Suppress progress messages |
Examples
# Update to the newest version
paperpile-stage update
# Install a specific version
paperpile-stage update 0.2.0
