PCO

pco drives a Mathpix Private Cloud OCR deployment running in your own
infrastructure. It speaks the same document API as scs, plus the deployment-only endpoints
for jobs over a cloud folder, status, and usage.

Point --endpoint at your deployment. A deployment usually needs no credentials of its own; pass
--token or the client-certificate flags if your ingress requires them. Set the endpoint once with
mpx configure (or MPX_ENDPOINT) to avoid repeating it.

convert is the one command that starts work, and it waits for the result. It takes a file, a local
folder, or a folder in your cloud storage.

mpx pco --endpoint http://pco.internal:8080 convert paper.pdf     # one file: paper.mmd + paper.lines.json beside it
mpx pco convert equation.png                                      # a single image, OCR'd through /v3/text
mpx pco convert ./scans/ ./out/ --formats md,docx                # a local folder: several at a time, a live progress bar
mpx pco convert s3://acme-docs/scans/ --formats md               # a bucket folder: a server-side job, watched to the end
mpx pco convert s3://acme-docs/in/ s3://acme-docs/out/           # write the job's outputs to a different folder

A file or a local folder is processed from your workstation by looping over /v3/pdf, and the
outputs are written locally - beside the inputs, or under a second folder you name. A cloud folder
(s3://, gs://, or an Azure blob URL) instead becomes a single server-side job over the
deployment’s own storage, and the outputs land in your bucket. Either way you see a live progress
bar and one line per file as it finishes. Every converted document yields mmd and lines.json;
--formats adds conversion formats on top, and a single image is OCR’d through the deployment’s
synchronous /v3/text automatically. A run records itself under _mathpix/<run_id>/ (local) or in
the bucket (cloud), so it can be stopped and picked up again.

mpx pco --endpoint http://pco.internal:8080 status     # versions, workers, license and metering
mpx pco --endpoint http://pco.internal:8080 usage --from 2026-09-01 --to 2026-09-30
mpx pco --endpoint http://pco.internal:8080 usage --export   # signed statement for an airgapped deployment

Manage server-side batch jobs over a folder in your bucket:

mpx pco --endpoint http://pco.internal:8080 jobs list
mpx pco --endpoint http://pco.internal:8080 jobs get JOB_ID
mpx pco --endpoint http://pco.internal:8080 jobs files JOB_ID --status error
mpx pco --endpoint http://pco.internal:8080 jobs report JOB_ID
mpx pco --endpoint http://pco.internal:8080 jobs retry JOB_ID
mpx pco --endpoint http://pco.internal:8080 jobs cancel JOB_ID

Moving a batch over from SCS classic? migrate-scs turns its option files into a /pco/v1/jobs
body you submit with convert --job-spec. It is pure translation - no network:

mpx pco migrate-scs --conversion-options conversion_options.json --ocr-options ocr_options.json --input-folder s3://acme-docs/in/ > job.json
mpx pco --endpoint http://pco.internal:8080 convert --job-spec job.json --dry-run   # check the spec, then run it without --dry-run

It maps conversion_options.json to options.conversion_formats, ocr_options.json to
options.ocr (dropping any option PCO does not support, with a note on stderr), and --ext-list to
options.extra_outputs; --max-pdf-pages, --pdf-per-page-timeout and --max-consumer-retries
become the job’s policy.

Transport flags on the pco service, layered on top of the global app_id / app_key:

Every command has --help for its full set of flags.