> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# CLI

The `paperwork` CLI wraps the whole [Paperwork API](/paperwork/api/overview). 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):

```bash
brew install cloudraker/tap/paperwork
```

**Shell installer** (macOS / Linux):

```bash
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:

```bash
paperwork --version
```

## Sign in

```bash
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.

```bash
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](/paperwork/developers/authentication) instead:

```bash
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

```bash
# 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:

```bash
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](/paperwork/developers/runs) for the lifecycle.

## Using it from agents

The CLI is the backbone of the [agent tooling](/paperwork/developers/agents): install the [paperwork skills](https://github.com/CloudRaker/cloudraker-paperwork-skills) and a coding agent can parse, extract, redact, fill, and sign documents without loading them into context.

## Environment variables

| Variable                | Effect                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| `PAPERWORK_TOKEN`       | API key; overrides the stored interactive login.                       |
| `PAPERWORK_BASE_URL`    | Override the API base URL (defaults to `https://api.cloudraker.com`).  |
| `PAPERWORK_AUTH_DOMAIN` | Override the sign-in host (defaults to `https://auth.cloudraker.com`). |
| `PAPERWORK_CLIENT_ID`   | Override the OAuth client (non-production environments).               |