CLI

The paperwork CLI wraps the whole Paperwork API. Every resource is a subcommand (paperwork extract extract, paperwork files upload, …), output is JSON, and it authenticates either interactively with your CloudRaker account or with an API key.

Install

Homebrew (macOS / Linux):

$
brew install cloudraker/tap/paperwork

Shell installer (macOS / Linux):

$
curl -fsSL https://paperwork.sh | sh

Prebuilt archives are also published per release at https://release.paperwork.sh/cli/latest/paperwork-<target>.tar.gz for aarch64-apple-darwin, x86_64-apple-darwin, aarch64-unknown-linux-musl, and x86_64-unknown-linux-musl.

Verify:

$
paperwork --version

Sign in

$
paperwork auth login

This opens the browser for a one-time device-code sign-in against auth.cloudraker.com. Add --no-browser on a headless machine — it prints a code and a URL you can open anywhere. The token lands in a local file store and refreshes itself.

$
paperwork auth status   # who am I / token state
$
paperwork auth logout   # drop the stored login

For CI or other non-interactive use, set an API key instead:

$
export PAPERWORK_TOKEN="<api key>"   # a .env in the cwd is auto-loaded too

PAPERWORK_TOKEN always wins over the stored login when both are present.

First calls

$
# any 200 means auth works
$
paperwork files list-files --limit 1
$
$
# parse a document to markdown + JSON
$
paperwork parse parse --json '{"file": {"url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf"}}'
$
$
# structured extraction with citations
$
paperwork extract extract --json '{
>
  "file": {"url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf"},
>
  "citations": true,
>
  "schema": {"type": "object", "properties": {"business_name": {"type": ["string", "null"]}}}
>
}'

Parameters go in as flags or as one --json payload. paperwork <resource> --help lists the methods for a resource; paperwork --help lists everything.

Waiting for runs

Every run-creating command accepts --wait <seconds> (0–120; the API defaults to holding the request open for 60s). Small digital-text documents usually finish inside the window. For OCR, audio, batches, pipelines, and signatures, fire with --wait 0 and poll:

$
RUN=$(paperwork extract extract --wait 0 --json '{...}')
$
paperwork runs get-run --id "$(echo "$RUN" | jq -r .id)" --wait 0

Terminal statuses are processed, failed, cancelled, and expired. See Runs for the lifecycle.

Using it from agents

The CLI is the backbone of the agent tooling: install the paperwork skills and a coding agent can parse, extract, redact, fill, and sign documents without loading them into context.

Environment variables