Convert
Reference for the `docutray convert` command in the DocuTray CLI — usage, flags, arguments, and examples.
Convert a document to structured data using a specified document type schema. Accepts a local file path or a public URL as the source. By default, processing is synchronous — the command waits and returns the extracted data. Use --async for long-running documents to poll for completion with status updates on stderr.
docutray convert SOURCE
Convert a document to structured data using a specified document type schema. Accepts a local file path or a public URL as the source. By default, processing is synchronous — the command waits and returns the extracted data. Use --async for long-running documents to poll for completion with status updates on stderr.
USAGE
$ docutray convert SOURCE -t <value> [--async] [--json] [--metadata <value>] [--timeout <value>]
ARGUMENTS
SOURCE File path or URL to convert
FLAGS
-t, --type=<value> (required) Document type code to use for extraction (see: docutray types list)
--async Use async processing with polling (default: false). Status updates are emitted to stderr.
--json Output as JSON (default when piped)
--metadata=<value> JSON metadata to attach to the conversion (e.g. '{"key":"value"}')
--timeout=<value> [default: 300] Polling timeout in seconds for async processing
DESCRIPTION
Convert a document to structured data using a specified document type schema. Accepts a local file path or a public
URL as the source. By default, processing is synchronous — the command waits and returns the extracted data. Use
--async for long-running documents to poll for completion with status updates on stderr.
EXAMPLES
Convert a local PDF using a document type
$ docutray convert invoice.pdf --type electronic-invoice
Convert a document from a URL
$ docutray convert https://example.com/doc.pdf -t electronic-invoice
Use async processing with status polling
$ docutray convert invoice.pdf -t electronic-invoice --async
Async with 10-minute timeout for large documents
$ docutray convert large-doc.pdf -t electronic-invoice --async --timeout 600
Attach custom metadata to the conversion
$ docutray convert invoice.pdf -t electronic-invoice --metadata '{"ref":"order-123"}'
DOCUMENTATION
Learn more: https://docs.docutray.com/cli/convertSee code: src/commands/convert.ts
docutray convert status CONVERSION-ID
Query the status of a conversion by its conversion ID. Use this to check on a conversion started with --async after a timeout, or to retrieve its result later. Returns the conversion status, the extracted data and its validation against the document type's JSON Schema and DSL rules when complete.
USAGE
$ docutray convert:status CONVERSION-ID [--json]
ARGUMENTS
CONVERSION-ID Conversion ID returned by "convert --async"
FLAGS
--json Output as JSON (default when piped)
DESCRIPTION
Query the status of a conversion by its conversion ID. Use this to check on a conversion started with --async after a
timeout, or to retrieve its result later. Returns the conversion status, the extracted data and its validation against
the document type's JSON Schema and DSL rules when complete.
EXAMPLES
Check the status of a conversion
$ docutray convert status conv_abc123
Output as JSON
$ docutray convert status conv_abc123 --json
Show only the validation of the extracted data
$ docutray convert status conv_abc123 | jq .validation
DOCUMENTATION
Learn more: https://docs.docutray.com/cli/convert/statusSee code: src/commands/convert/status.ts