Command reference¶
Every papio command, generated directly from the binary. Pass --json to any command for structured output; see the user guide for the operational workflow and the configuration reference for policy.
JSON output contract¶
Every list-shaped --json payload is a JSON object with exactly two keys, rows first: a named array and truncated (bool) — never a bare top-level array. An empty result is [], never null. truncated: true means the page filled its row cap (the default or --limit bound), so more rows may exist; it is not proof there are more — raise --limit or paginate to check.
This is the same envelope the MCP resources (papio://jobs and friends) already return, so one parser handles both surfaces:
Commands that return a single structured record — papio jobs get, papio doctor, papio status, papio batch report, papio zotio plan, papio inbox — return that object directly; they are not list envelopes and carry no truncated key.
Global flags¶
These flags are available on every command.
| Flag | Type | Default | Description |
|---|---|---|---|
--config |
string |
config TOML path | |
--json |
bool |
false |
emit structured JSON |
-v, --version |
bool |
false |
version for papio |
papio acquire¶
Submit one paper-acquisition request
| Flag | Type | Default | Description |
|---|---|---|---|
--access-mode |
string |
per-request access-mode override | |
--arxiv |
string |
arXiv ID | |
--author |
stringSlice |
[] |
author (repeatable) |
--auto-import |
bool |
false |
plan and apply zotio import automatically when ready |
--batch |
string |
submit works from a JSONL, RIS, BibTeX, CSL-JSON, or MEDLINE/NBIB file (or - for standard input) | |
--collection |
string |
target Zotero collection name (key when used with --from-zotio) | |
--consumer |
string |
name the submitting consumer, for per-consumer accounting on a shared daemon | |
--deny-source |
stringSlice |
[] |
deny this source (repeatable) |
--desired-version |
string |
any |
published, accepted, preprint, or any |
--doi |
string |
DOI | |
--force |
bool |
false |
create a fresh job even when this work is already in flight |
--from-digest |
int64 |
0 |
queue pending entries from an alert watch |
--from-zotio |
bool |
false |
queue zotio items missing an attached PDF |
--include-owned |
bool |
false |
with --batch, submit works already carrying a PDF in zotio |
--isbn |
string |
ISBN | |
--keys |
stringArray |
[] |
digest work key to queue (repeatable) |
--label |
string |
query context; also the default target collection when --collection is unset | |
--limit |
int |
25 |
maximum zotio items to queue |
--max-cost |
float64 |
0 |
maximum paid-source cost in USD |
--openalex |
string |
OpenAlex work ID | |
--pmid |
string |
PubMed ID | |
--request-id |
string |
stable idempotency key | |
--resolver |
string |
named institutional OpenURL resolver profile | |
--source |
stringSlice |
[] |
allow only this source (repeatable) |
--title |
string |
work title | |
--wait |
bool |
false |
wait for a terminal or human-action state |
--year |
int |
0 |
publication year |
--zotio-item-key |
string |
existing Zotero item key |
papio actions¶
Inspect required human actions
papio actions dismiss¶
Close a stale human action without touching its job
Close a stale human action without touching its job.
An advisory on a terminal job has no other way out: cancel refuses a terminal job, resolve is identity-review only, and the startup sweep deliberately leaves informational advisories alone so a real trace survives. Without this, retiring one meant editing the database or retrying the job purely to cancel it again.
--revision guards against dismissing an action that changed after you
listed it; take it from papio actions list --json.
| Flag | Type | Default | Description |
|---|---|---|---|
--revision |
int64 |
0 |
revision the action had when you listed it |
papio actions list¶
List open human actions
List open human actions.
An action queued long enough to look abandoned is reported stale — age_seconds and stale in --json, a trailing marker in the text listing — against the configured actions.stale_after_seconds. Staleness is a label and nothing else: no handoff is ever cancelled on a timer, because giving up on an acquisition is your call.
| Flag | Type | Default | Description |
|---|---|---|---|
--all |
bool |
false |
include resolved actions |
--consumer |
string |
only actions whose job was submitted under this consumer name | |
--limit |
int |
100 |
maximum rows (1-500) |
papio actions open¶
Open the current browser handoff queue
Open the current browser handoff queue.
With no selector this opens the whole openable queue, newest first. --job or --action opens exactly one row instead, for a caller that ranked the queue itself and wants the row it chose. A job holding several open actions is refused with their ids rather than resolved by picking one, and a selector naming no open action is an error: falling back to the head of the queue would open somebody else's handoff and report success.
The selector is for choosing a row, not for iterating the queue. A background caller that loops it over every row has built the autonomous drain ADR-0009 does not ratify: your browser is one serial surface, and filling it with tabs nobody asked for is not acquisition progress.
| Flag | Type | Default | Description |
|---|---|---|---|
--action |
int64 |
0 |
open only this action id |
--dry-run |
bool |
false |
print URLs without opening them |
--job |
string |
open only this job's open action | |
--limit |
int |
0 |
maximum actions to open (default all) |
papio actions resolve¶
Accept or reject a parked identity or unsafe-PDF review
| Flag | Type | Default | Description |
|---|---|---|---|
--accept |
bool |
false |
accept the identity review |
--reject |
bool |
false |
reject the identity review |
papio activity¶
Show recent daemon activity
| Flag | Type | Default | Description |
|---|---|---|---|
--job |
string |
filter activity to one job ID | |
--limit |
int |
30 |
maximum activity rows (1-200) |
papio adapter¶
Inspect provider and adapter interactions
papio adapter capture¶
Capture a provider page through the connected browser
| Flag | Type | Default | Description |
|---|---|---|---|
--provider |
string |
provider adapter id | |
--scenario |
string |
fixture scenario | |
--settle-ms |
int64 |
0 |
milliseconds to settle after page load (0-10000) |
papio adapter captures¶
List stored diagnostic page captures
papio adapter captures purge¶
Remove stored diagnostic page captures
| Flag | Type | Default | Description |
|---|---|---|---|
--host |
string |
purge captures for one host |
papio adapter diagnose¶
Build a sanitized support report for a job
papio adapter repair¶
Scaffold a reviewed adapter repair workspace
| Flag | Type | Default | Description |
|---|---|---|---|
--provider |
string |
provider adapter id (must match daemon capture metadata) | |
--scenario |
string |
fixture scenario (must match daemon capture metadata) |
papio artifacts¶
Inspect validated immutable artifacts
papio artifacts get¶
Show a validated artifact
| Flag | Type | Default | Description |
|---|---|---|---|
--sha256 |
bool |
false |
interpret argument as an artifact hash |
papio artifacts locate¶
Print where one job's validated artifact bytes live
papio artifacts validation¶
Print the full validation report for every candidate a job validated
Print the full validation report for every candidate a job validated.
artifacts get returns the shared, content-addressed artifact row —
which is all it can return, because an artifact belongs to every job
that obtained the same bytes (ADR-0007). This is the per-job evidence:
the payload gate, the structural parse, text extraction, and the
identity decision, each with the reasons and capability evidence behind
it, for the candidates that were kept AND the ones that were rejected.
Each report is a versioned document (validation-report/1). A job validated before this evidence was recorded lists no reports; that is an absence, not an empty verdict.
papio batch¶
Inspect persisted acquisition batches
papio batch report¶
Join a batch manifest with live acquisition outcomes
| Flag | Type | Default | Description |
|---|---|---|---|
--markdown |
bool |
false |
emit an agent-ready Markdown digest |
papio bench¶
Run the hermetic comparative acquisition benchmark over a cohort file
| Flag | Type | Default | Description |
|---|---|---|---|
--cohort |
string |
path to a papio-bench-cohort/1 document | |
--fixtures |
string |
fixture directory (default: the cohort file's sibling "fixtures" directory) |
papio browser¶
Inspect and switch connected browser sessions
papio browser permit¶
Recover daemon-owned browser effect permits
papio browser permit resolve¶
Release one unknown-completion browser effect permit
Release one exact unknown-completion effect permit after an operator has independently resolved whether its browser effect completed. This is break-glass recovery; it never releases a held permit.
| Flag | Type | Default | Description |
|---|---|---|---|
--reason |
string |
operator reason recorded in the durable audit event |
papio browser reload¶
Reload the connected development-mode extension from disk
Reload the connected development-mode extension from disk, replacing the manual chrome://extensions Reload click. It only affects an unpacked extension, because the extension refuses the command unless chrome.management.getSelf() reports installType "development". A new session id is the proof the new bundle is live.
| Flag | Type | Default | Description |
|---|---|---|---|
--timeout |
duration |
15s |
how long to wait for the reloaded extension to reconnect (0 waits not at all) |
papio browser sessions¶
List browser sessions connected since daemon start
papio browser use¶
Give one browser session the papio offer/handoff flow
| Flag | Type | Default | Description |
|---|---|---|---|
--latest |
bool |
false |
switch to the most recently active pending session |
papio bundle¶
Read and export validated acquisition bundles
papio bundle document¶
Print the acquisition bundle without writing it anywhere
papio bundle export¶
Export an idempotent bundle directory
| Flag | Type | Default | Description |
|---|---|---|---|
-o, --output |
string |
destination directory |
papio config¶
Manage papio configuration
papio config init¶
Write explicit first-run configuration
| Flag | Type | Default | Description |
|---|---|---|---|
--access-mode |
string |
required: conservative, assisted, or delegated | |
--data-dir |
string |
artifact and database directory | |
--email |
string |
contact email for polite APIs | |
--force |
bool |
false |
replace an existing config |
papio daemon¶
Run or control the local acquisition daemon
| Flag | Type | Default | Description |
|---|---|---|---|
--socket |
string |
Unix socket path |
papio daemon status¶
Check the running daemon without autostarting one
papio daemon stop¶
Stop the running daemon without autostarting one
papio delivery¶
Manage document-delivery and ILL requests
papio delivery cancel¶
Cancel a document-delivery request, where the provider supports it
papio delivery confirm-absent¶
Confirm no request exists at the provider, cancel the stale row, and reopen reconciliation for a deliberate decision (v1 never auto-resubmits)
papio delivery confirm-exists¶
Confirm a lodged request exists at the provider and resume polling
papio delivery get¶
Show a job's document-delivery request and compiled gate
papio delivery history¶
Show a delivery request's history for reconciliation (Decision 4's open_request_history)
papio delivery resume¶
Clear a live delivery request's poll-failure bookkeeping (e.g. a contract-drift park) so the next poll is no longer a no-op
papio delivery submit¶
Run the document-delivery Branch/gate decision for a job
papio doctor¶
Check acquisition readiness and local integrations
papio export¶
Export normalized citation records (CSL-JSON, RIS, BibTeX)
| Flag | Type | Default | Description |
|---|---|---|---|
--format |
string |
citation format: csl-json, ris, or bibtex (default csl-json, inferred from -o's extension) | |
--include-duplicates |
bool |
false |
keep records whose canonical identity repeats instead of collapsing them |
-o, --output |
string |
write citations to this file instead of stdout (required with --json) |
papio export batch¶
Export every work in the batch manifest in manifest order, including skipped and unavailable works
papio export job¶
Export the named jobs in argument order (any state: citation metadata stays useful when retrieval failed)
papio export ledger¶
Export one record per canonical work (ready acquisitions by default)
| Flag | Type | Default | Description |
|---|---|---|---|
--consumer |
string |
only works submitted by this consumer | |
--since |
string |
only works submitted after this instant (RFC3339) or within this duration (Go form, e.g. 720h) | |
--state |
string |
ready |
which works to export: ready (validated acquisitions) or any (every job) |
papio export watch¶
Export a watch's pending digest entries
papio failures¶
Aggregate unavailable and parked acquisition reasons
| Flag | Type | Default | Description |
|---|---|---|---|
--by-provider |
bool |
false |
group by provider host/source instead of reason |
--limit |
int |
20 |
maximum aggregate rows (1-200) |
papio grabs¶
Manage captured PDF grabs
papio grabs binds¶
List captures papio filed automatically, without asking
List captures papio bound to a pending job on its own, newest first.
papio only does this when a settled, DOI-less capture qualifies exactly one pending job; everything else still parks for a human. Because there is no unbind command, this listing — the rule version, how many candidates were on the table, and the evidence that made one of them the winner — is the only way to check an automatic filing after the fact.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
50 |
maximum autonomous binds to list (default 50, max 200) |
papio grabs confirm¶
File a parked capture against the job you picked
Bind a parked capture to a specific pending job chosen by a human —
typically the top (or any) row of papio grabs suggest's ranking.
papio still refuses the pick if the document's own front matter names a different paper: extracted identity outranks a human pick, the same rule autonomous binding already applies to itself. A refusal changes nothing — no job is created and the capture stays parked exactly as it was before.
| Flag | Type | Default | Description |
|---|---|---|---|
--job |
string |
pending job id to file this capture against |
papio grabs identify¶
Bind an operator-supplied identifier to a captured PDF grab
| Flag | Type | Default | Description |
|---|---|---|---|
--arxiv |
string |
identify by arXiv ID | |
--doi |
string |
identify by DOI | |
--pmid |
string |
identify by PubMed ID |
papio grabs suggest¶
Rank pending jobs against a parked capture: which paper is this?
Rank the pending jobs that best match a capture which parked instead of
binding on its own, most-likely first, with the evidence behind each
ranking. Nothing is filed by running this — it only orders the candidates
a human would otherwise have to hunt through by hand; pick one and run
papio grabs confirm to actually file it.
If the captured file states its own DOI, PMID, or arXiv ID in its front
matter, that identifier is printed first: papio grabs identify with that
value is faster and more certain than picking from the ranked list below it.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
5 |
maximum ranked suggestions to return (default 5, max 25) |
papio inbox¶
Show the triage inbox
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
0 |
maximum items (default 50, maximum 100) |
papio inbox counts¶
Show complete triage inbox counts
papio inbox decide¶
Acquire or dismiss one triage inbox item
| Flag | Type | Default | Description |
|---|---|---|---|
--op |
string |
acquire or dismiss | |
--watch-scope |
string |
all |
for dismiss: all, or a comma-separated list of watch IDs |
papio init¶
Set up papio for a first run
| Flag | Type | Default | Description |
|---|---|---|---|
--attachment-mode |
string |
zotio attachment mode: stored or linked-file | |
--check-updates |
bool |
true |
check for papio and zotio updates once a day via GitHub releases (sends nothing else) |
--email |
string |
contact email for polite API pools | |
--extension-id |
string |
Chrome extension ID allowed to reach the native host, or an unpacked extension folder path (papio computes its ID) | |
--firefox-extension-id |
string |
Firefox add-on ID allowed to reach the native host | |
--institution-url |
string |
library discovery or resolver URL; papio derives the OpenURL base | |
--libkey-library-id |
string |
numeric Third Iron library id, or a BrowZine/LibKey.io URL containing /libraries/ |
|
--non-interactive |
bool |
false |
do not prompt; retain existing values unless a flag overrides them |
--openurl-base |
string |
institution OpenURL resolver base URL | |
--proquest-account-id |
string |
ProQuest account id, or a ProQuest URL containing accountid= | |
--shibboleth-entity-id |
string |
Shibboleth IdP entityID for federated login-routing | |
--skip-browser |
bool |
false |
skip Chrome extension and native-host setup |
--zotio-path |
string |
zotio executable path |
papio jobs¶
Inspect and control acquisition jobs
papio jobs add-component¶
Add a supplement or appendix to a job
| Flag | Type | Default | Description |
|---|---|---|---|
--role |
string |
component role: supplement or appendix |
papio jobs cancel¶
Cancel a nonterminal job
papio jobs diagnose¶
Explain why one job needs attention and what can happen next
papio jobs failures¶
Group acquisition jobs that need attention
Group acquisition jobs that need attention.
Incident fingerprints omit raw hosts and identifiers and are keyed per installation; local output intentionally includes bounded safety_domain and registrable host_family labels for diagnosis.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
50 |
maximum groups (1-200) |
--since |
string |
include jobs updated since a duration or RFC3339 timestamp |
papio jobs get¶
Show one job with events and actions
| Flag | Type | Default | Description |
|---|---|---|---|
--wait |
bool |
false |
wait for completion or human action |
papio jobs incidents¶
Group decisive provider incidents
Group decisive provider incidents by keyed failure shape.
The fingerprint omits raw hosts and identifiers and is keyed per installation; local output intentionally includes bounded safety_domain and registrable host_family labels for diagnosis.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
50 |
maximum groups (1-200) |
--since |
string |
include incidents recorded since a duration or RFC3339 timestamp |
papio jobs list¶
List jobs
| Flag | Type | Default | Description |
|---|---|---|---|
--consumer |
string |
only jobs submitted under this consumer name | |
--limit |
int |
100 |
maximum rows (1-500) |
--state |
string |
filter by exact job state |
papio jobs receipt¶
Show the outcome and component index for one job
papio jobs repair-awaiting-human¶
Return an orphaned awaiting-human job with no open actions to resolving
papio jobs retry¶
Explicitly retry a failed, unavailable, or retry-wait job
papio jobs show¶
Show one job with events and actions
| Flag | Type | Default | Description |
|---|---|---|---|
--wait |
bool |
false |
wait for completion or human action |
papio mcp¶
Serve papio tools and resources over MCP stdio
papio native-host¶
Manage browser native-messaging host registration
papio native-host install¶
Register native-messaging host manifests and the host executable
| Flag | Type | Default | Description |
|---|---|---|---|
--firefox-manifest-dir |
string |
override the Firefox native-messaging manifest directory | |
--manifest-dir |
string |
override the Chrome native-messaging manifest directory |
papio native-host status¶
Report native-messaging host registration state
| Flag | Type | Default | Description |
|---|---|---|---|
--firefox-manifest-dir |
string |
override the Firefox native-messaging manifest directory | |
--manifest-dir |
string |
override the Chrome native-messaging manifest directory |
papio native-host uninstall¶
Remove native-messaging host manifests and the host executable
| Flag | Type | Default | Description |
|---|---|---|---|
--firefox-manifest-dir |
string |
override the Firefox native-messaging manifest directory | |
--manifest-dir |
string |
override the Chrome native-messaging manifest directory |
papio notify¶
Inspect and test notification routing
papio notify preview¶
Preview notification copy without sending
| Flag | Type | Default | Description |
|---|---|---|---|
--count |
int |
1 |
number of events represented in the preview |
papio notify show¶
Show effective notification routing
papio notify test¶
Send one local notification test
papio pulse¶
Show the daemon's current work pulse
papio search¶
Search configured discovery backends for scholarly works
| Flag | Type | Default | Description |
|---|---|---|---|
--cited-by |
string |
DOI to find papers it cites (backward references; OpenAlex cited_by: filter) | |
--cites |
string |
DOI to find papers citing it (forward citations; OpenAlex cites: filter) | |
--limit |
int |
20 |
maximum results (1-50) |
--new-only |
bool |
false |
omit works already in your library; filters after --limit and may return fewer results |
--oa-only |
bool |
false |
return only open-access works |
--related-to |
string |
DOI to find OpenAlex-related papers (related_to: filter) | |
--source |
string |
discovery backend: openalex or semanticscholar (default: all configured) | |
--year-from |
int |
0 |
minimum publication year |
--year-to |
int |
0 |
maximum publication year |
papio stats¶
Show lifetime acquisition totals by access basis
papio stats page-bulk¶
Show page-bulk scan/submit funnel and identifier yield
papio status¶
Show active and recent acquisition jobs
| Flag | Type | Default | Description |
|---|---|---|---|
--follow |
bool |
false |
refresh every 2 seconds |
papio version¶
Print version information
papio watch¶
Manage scheduled discovery watchlists
papio watch add¶
Add a scheduled discovery watch
Add a scheduled discovery watch. Backfill watches take no query. Alert-mode discovery watches report new works without acquiring them.
| Flag | Type | Default | Description |
|---|---|---|---|
--cadence |
string |
daily |
daily, weekly, or Nh |
--cited-by |
string |
DOI to find papers it cites (backward references; OpenAlex cited_by: filter) | |
--cites |
string |
DOI to find papers citing it (forward citations; OpenAlex cites: filter) | |
--collection |
string |
zotio collection for queued papers | |
--kind |
string |
discovery |
watch kind: discovery or backfill |
--label |
string |
human label (defaults to query) | |
--limit-per-run |
int |
10 |
maximum new papers queued per run (1-50) |
--mode |
string |
acquire |
discovery mode: acquire or alert |
--oa-only |
bool |
false |
return only open-access works |
--related-to |
string |
DOI to find OpenAlex-related papers (related_to: filter) | |
--year-from |
int |
0 |
minimum publication year |
--year-to |
int |
0 |
maximum publication year |
papio watch digest¶
Show recently reported works from an alert watch
| Flag | Type | Default | Description |
|---|---|---|---|
--limit |
int |
100 |
maximum digest entries to show (1-500) |
papio watch digest clear¶
Clear pending works from an alert watch digest
papio watch list¶
List scheduled discovery watches
papio watch remove¶
Remove a scheduled discovery watch
papio watch run¶
Force-run a scheduled discovery watch now
papio zotio¶
Preview and apply Zotero integration through zotio
papio zotio apply¶
Apply one immutable zotio plan after SHA-256 confirmation
| Flag | Type | Default | Description |
|---|---|---|---|
--confirm-sha256 |
string |
Exact confirmation SHA-256 printed by papio zotio plan |
papio zotio import-backfill¶
Backfill stranded ready papers into Zotero (dry-run by default)
Deliver validated ready jobs whose Zotero import never succeeded.
Dry-run is the default: the command reports what it would import, which papers are already owned (and would be marked duplicate), and which are expected to fail (for example bundle validation on an empty title). Pass --apply to write to your library.
Jobs submitted without policy.auto_import are excluded unless you pass --include-not-requested, because importing them was never requested.
| Flag | Type | Default | Description |
|---|---|---|---|
--apply |
bool |
false |
apply imports to the configured Zotero library (default is dry-run) |
--cursor |
string |
resume after the cursor returned by a previous invocation | |
--include-not-requested |
bool |
false |
include ready jobs that did not request policy.auto_import |
--limit |
int |
50 |
maximum jobs per invocation (1-50) |
papio zotio plan¶
Export ready jobs and preview exact zotio mutations
papio zotio preflight¶
Verify the configured zotio version and capabilities
papio zotio tags¶
Manage the exception-tag ledger on linked Zotero items
papio zotio tags reconcile¶
Converge papio:needs-action / papio:unavailable tags with current job states