@docutray/cli

Official DocuTray CLI — AI-powered document processing from the command line.

Designed for AI agents (Claude Code, Copilot, Codex) and automation pipelines. All output is JSON by default, with clear exit codes and no interactive prompts (except login).

Installation

npm install -g @docutray/cli

Or run directly without installing:

npx @docutray/cli <command>

Quickstart

# Authenticate with your API key
docutray login

# List available document types
docutray types list

# Convert a document to structured data
docutray convert invoice.pdf --type electronic-invoice

Commands

• docutray autocomplete [SHELL]
• docutray convert SOURCE
• docutray identify SOURCE
• docutray login [API-KEY]
• docutray logout
• docutray status
• docutray steps run STEP-ID SOURCE
• docutray steps status EXECUTION-ID
• docutray types create
• docutray types export CODE
• docutray types get CODE
• docutray types list
• docutray types update CODE

docutray autocomplete [SHELL]

Display autocomplete installation instructions.

USAGE
  $ docutray autocomplete [SHELL] [-r]

ARGUMENTS
  [SHELL]  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  Display autocomplete installation instructions.

EXAMPLES
  $ docutray autocomplete

  $ docutray autocomplete bash

  $ docutray autocomplete zsh

  $ docutray autocomplete powershell

  $ docutray autocomplete --refresh-cache

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/autocomplete

See code: @oclif/plugin-autocomplete

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>]
    [--webhook-url <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
      --webhook-url=<value>  Webhook URL to receive a POST notification when conversion completes

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

  Convert with webhook notification on completion

    $ docutray convert receipt.jpg -t receipt --webhook-url https://example.com/hook

  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/convert

See code: src/commands/convert.ts

docutray identify SOURCE

Identify the type of a document by analyzing its content. Returns the best-matching document type along with alternative matches ranked by confidence score. Use --types to restrict identification to a specific set of document types. Accepts a local file path or a public URL.

USAGE
  $ docutray identify SOURCE [--async] [--json] [--types <value>]

ARGUMENTS
  SOURCE  File path or URL to identify

FLAGS
  --async          Use async processing with polling (default: false). Status updates are emitted to stderr.
  --json           Output as JSON (default when piped)
  --types=<value>  Comma-separated list of document type codes to restrict identification (e.g. invoice,receipt)

DESCRIPTION
  Identify the type of a document by analyzing its content. Returns the best-matching document type along with
  alternative matches ranked by confidence score. Use --types to restrict identification to a specific set of document
  types. Accepts a local file path or a public URL.

EXAMPLES
  Identify a local document

    $ docutray identify document.pdf

  Identify a document from a URL

    $ docutray identify https://example.com/doc.pdf

  Restrict to specific document types

    $ docutray identify document.pdf --types invoice,receipt,contract

  Force JSON output

    $ docutray identify document.pdf --json

  Use async processing with status polling

    $ docutray identify document.pdf --async

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/identify

See code: src/commands/identify.ts

docutray login [API-KEY]

Configure your DocuTray API key for authentication. When called without arguments, prompts to choose between pasting an existing API key or authenticating via OAuth2 in the browser. For non-interactive shells (CI, AI coding agents), use --oauth to drive the OAuth flow end-to-end without a TTY: the CLI prints the authorization URL on stderr, opens your browser, waits for the callback, and writes the resulting API key to ~/.config/docutray/config.json.

USAGE
  $ docutray login [API-KEY] [--api-key <value>] [--base-url <value>] [--json] [--no-browser] [--oauth]
    [--timeout <value>]

ARGUMENTS
  [API-KEY]  API key to save (omit for interactive prompt)

FLAGS
  --api-key=<value>   API key for non-interactive login
  --base-url=<value>  Custom base URL for the DocuTray API (default: https://app.docutray.com)
  --json              Output as JSON (default when piped)
  --no-browser        Skip opening the browser; print the URL only (--oauth only)
  --oauth             Login via OAuth in the browser (works without a TTY)
  --timeout=<value>   [default: 180] OAuth callback timeout in seconds (--oauth only)

DESCRIPTION
  Configure your DocuTray API key for authentication. When called without arguments, prompts to choose between pasting
  an existing API key or authenticating via OAuth2 in the browser. For non-interactive shells (CI, AI coding agents),
  use --oauth to drive the OAuth flow end-to-end without a TTY: the CLI prints the authorization URL on stderr, opens
  your browser, waits for the callback, and writes the resulting API key to ~/.config/docutray/config.json.

EXAMPLES
  Interactive login — choose API key or OAuth2 browser login

    $ docutray login

  Login via OAuth in the browser (works in agents/CI without a TTY)

    $ docutray login --oauth

  Print the OAuth URL but do not open the browser

    $ docutray login --oauth --no-browser

  Non-interactive login with API key as argument

    $ docutray login dt_live_abc123

  Non-interactive login with API key flag

    $ docutray login --api-key dt_live_abc123

  Login with a custom API base URL

    $ docutray login --base-url https://staging.docutray.com

  Alternative: use env var instead of login

    DOCUTRAY_API_KEY=dt_live_abc123 docutray status

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/login

See code: src/commands/login.ts

docutray logout

Clear stored credentials by removing the local configuration file. This does not invalidate the API key itself — it only removes it from this machine. Has no effect if you are authenticating via the DOCUTRAY_API_KEY environment variable.

USAGE
  $ docutray logout [--json]

FLAGS
  --json  Output as JSON (default when piped)

DESCRIPTION
  Clear stored credentials by removing the local configuration file. This does not invalidate the API key itself — it
  only removes it from this machine. Has no effect if you are authenticating via the DOCUTRAY_API_KEY environment
  variable.

EXAMPLES
  Remove stored API key from local config

    $ docutray logout

  Logout and verify authentication is cleared

    $ docutray logout && docutray status

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/logout

See code: src/commands/logout.ts

docutray status

Show current authentication status and configuration. Displays whether you are authenticated, the masked API key, the credential source (environment variable or config file), the API base URL, and the config file path. Useful for verifying your setup before running commands.

USAGE
  $ docutray status [--json]

FLAGS
  --json  Output as JSON (default when piped)

DESCRIPTION
  Show current authentication status and configuration. Displays whether you are authenticated, the masked API key, the
  credential source (environment variable or config file), the API base URL, and the config file path. Useful for
  verifying your setup before running commands.

EXAMPLES
  Check current authentication status

    $ docutray status

  Output as JSON (default when piped)

    $ docutray status --json

  Verify env var authentication is detected

    DOCUTRAY_API_KEY=dt_live_abc123 docutray status

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/status

See code: src/commands/status.ts

docutray steps run STEP-ID SOURCE

Execute a processing step on a document. Steps are reusable processing pipelines configured in the DocuTray dashboard. By default, the command waits for the step to complete and returns the result. Use --no-wait to return the execution status immediately without polling. Accepts a local file path or a public URL as the document source.

USAGE
  $ docutray steps:run STEP-ID SOURCE [--json] [--metadata <value>] [--no-wait] [--webhook-url <value>]

ARGUMENTS
  STEP-ID  Step ID to execute
  SOURCE   File path or URL to process

FLAGS
  --json                 Output as JSON (default when piped)
  --metadata=<value>     JSON metadata to attach to the execution (e.g. '{"key":"value"}')
  --no-wait              Return immediately with execution status instead of waiting for completion (default: false)
  --webhook-url=<value>  Webhook URL to receive a POST notification when the step completes

DESCRIPTION
  Execute a processing step on a document. Steps are reusable processing pipelines configured in the DocuTray dashboard.
  By default, the command waits for the step to complete and returns the result. Use --no-wait to return the execution
  status immediately without polling. Accepts a local file path or a public URL as the document source.

EXAMPLES
  Run a step on a local file and wait for results

    $ docutray steps run extract-fields invoice.pdf

  Run a step on a document URL

    $ docutray steps run extract-fields https://example.com/doc.pdf

  Start execution and return immediately (async)

    $ docutray steps run extract-fields invoice.pdf --no-wait

  Attach custom metadata to the execution

    $ docutray steps run extract-fields invoice.pdf --metadata '{"ref":"order-123"}'

  Receive a webhook notification on completion

    $ docutray steps run extract-fields invoice.pdf --webhook-url https://example.com/hook

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/steps/run

See code: src/commands/steps/run.ts

docutray steps status EXECUTION-ID

Query the current status of a step execution by its execution ID. Use this to check progress on executions started with --no-wait, or to retrieve results after receiving a webhook notification. Returns the execution status, progress, and result data when complete.

USAGE
  $ docutray steps:status EXECUTION-ID [--json]

ARGUMENTS
  EXECUTION-ID  Step execution ID to query

FLAGS
  --json  Output as JSON (default when piped)

DESCRIPTION
  Query the current status of a step execution by its execution ID. Use this to check progress on executions started
  with --no-wait, or to retrieve results after receiving a webhook notification. Returns the execution status, progress,
  and result data when complete.

EXAMPLES
  Check the status of an execution

    $ docutray steps status exec_abc123

  Output as JSON

    $ docutray steps status exec_abc123 --json

  Start async execution then check its status

    $ docutray steps run my-step doc.pdf --no-wait | jq -r .id | xargs docutray steps status

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/steps/status

See code: src/commands/steps/status.ts

docutray types create

Create a new document type. Defines an extraction schema that DocuTray uses when converting documents. Requires a name, code, description, and JSON schema. The schema can be provided as a file path or inline JSON string. Files exported via "types export" are also accepted: the inner jsonSchema is extracted automatically.

USAGE
  $ docutray types:create --code <value> --description <value> --name <value> --schema <value> [--conversion-mode
    json|toon|multi_prompt] [--identify-hints <value>] [--json] [--keep-ordering] [--prompt-hints <value>] [--publish |
    --draft]

FLAGS
  --code=<value>              (required) Unique code identifier (lowercase, numbers, underscores)
  --conversion-mode=<option>  Conversion mode
                              <options: json|toon|multi_prompt>
  --description=<value>       (required) Description of the document type
  --[no-]draft                Create as draft (default: true)
  --identify-hints=<value>    Hints for automatic document identification
  --json                      Output as JSON (default when piped)
  --keep-ordering             Preserve property ordering in extraction output
  --name=<value>              (required) Document type name
  --prompt-hints=<value>      General extraction prompt hints
  --publish                   Publish immediately (equivalent to --no-draft)
  --schema=<value>            (required) JSON schema: file path or inline JSON string

DESCRIPTION
  Create a new document type. Defines an extraction schema that DocuTray uses when converting documents. Requires a
  name, code, description, and JSON schema. The schema can be provided as a file path or inline JSON string. Files
  exported via "types export" are also accepted: the inner jsonSchema is extracted automatically.

EXAMPLES
  Create from a schema file

    $ docutray types create --name "Invoice" --code invoice --description "Standard invoice" --schema schema.json

  Create with inline JSON schema

    $ docutray types create --name "Invoice" --code invoice --description "Standard invoice" --schema \
      '{"type":"object","properties":{"total":{"type":"number"}}}'

  Round-trip: export an existing type and re-create it

    $ docutray types export factura -o factura.json && docutray types create --name "Factura Copy" --code \
      factura_copy --description "Copy of factura" --schema factura.json

  Create and publish immediately

    $ docutray types create --name "Invoice" --code invoice --description "Standard invoice" --schema schema.json \
      --publish

  Create with a specific conversion mode

    $ docutray types create --name "Invoice" --code invoice --description "Standard invoice" --schema schema.json \
      --conversion-mode toon

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/types/create

See code: src/commands/types/create.ts

docutray types export CODE

Export a document type definition to JSON format. By default, writes to stdout for piping or redirection. Use --output to write directly to a file. Useful for backing up type definitions, version-controlling them in Git, or migrating types between environments.

USAGE
  $ docutray types:export CODE [--force] [--json] [-o <value>]

ARGUMENTS
  CODE  Document type code

FLAGS
  -o, --output=<value>  Output file path. If omitted, writes to stdout.
      --force           Overwrite existing file
      --json            Output as JSON (default when piped)

DESCRIPTION
  Export a document type definition to JSON format. By default, writes to stdout for piping or redirection. Use --output
  to write directly to a file. Useful for backing up type definitions, version-controlling them in Git, or migrating
  types between environments.

EXAMPLES
  Export a document type to stdout

    $ docutray types export electronic-invoice

  Export directly to a file

    $ docutray types export electronic-invoice -o invoice-type.json

  Export using shell redirection

    $ docutray types export electronic-invoice > backup.json

  Export and pretty-print with jq

    $ docutray types export electronic-invoice | jq .

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/types/export

See code: src/commands/types/export.ts

docutray types get CODE

Get the full details of a document type by its code. Returns the type name, description, field schema, and configuration. Use this to inspect a document type before converting documents or to verify type settings.

USAGE
  $ docutray types:get CODE [--json]

ARGUMENTS
  CODE  Document type code

FLAGS
  --json  Output as JSON (default when piped)

DESCRIPTION
  Get the full details of a document type by its code. Returns the type name, description, field schema, and
  configuration. Use this to inspect a document type before converting documents or to verify type settings.

EXAMPLES
  Get full details of a document type

    $ docutray types get electronic-invoice

  Output full JSON (includes JSON Schema)

    $ docutray types get electronic-invoice --json

  Extract just the JSON Schema (useful for scripts)

    $ docutray types get electronic-invoice | jq .jsonSchema

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/types/get

See code: src/commands/types/get.ts

docutray types list

List available document types with pagination and search. Document types define the extraction schema used when converting documents. Results are paginated — use --page and --limit to navigate through large result sets. Use --search to filter by name.

USAGE
  $ docutray types:list [--json] [--limit <value>] [--page <value>] [--search <value>]

FLAGS
  --json            Output as JSON (default when piped)
  --limit=<value>   [default: 20] Number of results per page
  --page=<value>    [default: 1] Page number for pagination
  --search=<value>  Filter document types by name (case-insensitive substring match)

DESCRIPTION
  List available document types with pagination and search. Document types define the extraction schema used when
  converting documents. Results are paginated — use --page and --limit to navigate through large result sets. Use
  --search to filter by name.

EXAMPLES
  List all document types (first page, default 20 results)

    $ docutray types list

  Search for document types by name

    $ docutray types list --search invoice

  Paginate through results

    $ docutray types list --limit 50 --page 2

  Force JSON output

    $ docutray types list --json

  Extract just the type codes (useful for scripting)

    $ docutray types list | jq ".data[].codeType"

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/types/list

See code: src/commands/types/list.ts

docutray types update CODE

Update an existing document type. Allows modifying name, description, schema, prompt hints, and other settings. At least one field to update must be provided. The code identifier cannot be changed.

USAGE
  $ docutray types:update CODE [--conversion-mode json|toon|multi_prompt] [--description <value>]
    [--identify-hints <value>] [--json] [--keep-ordering] [--name <value>] [--prompt-hints <value>] [--publish |
    --draft] [--schema <value>]

ARGUMENTS
  CODE  Document type code to update

FLAGS
  --conversion-mode=<option>  Conversion mode
                              <options: json|toon|multi_prompt>
  --description=<value>       New description
  --[no-]draft                Set draft status
  --identify-hints=<value>    Hints for automatic document identification
  --json                      Output as JSON (default when piped)
  --[no-]keep-ordering        Preserve property ordering in extraction output
  --name=<value>              New name
  --prompt-hints=<value>      General extraction prompt hints
  --publish                   Publish immediately (sets draft to false)
  --schema=<value>            New JSON schema: file path or inline JSON string

DESCRIPTION
  Update an existing document type. Allows modifying name, description, schema, prompt hints, and other settings. At
  least one field to update must be provided. The code identifier cannot be changed.

EXAMPLES
  Update the name

    $ docutray types update invoice --name "Updated Invoice"

  Update the schema from a file

    $ docutray types update invoice --schema new-schema.json

  Update prompt hints

    $ docutray types update invoice --prompt-hints "Use dd/mm/yyyy for dates"

  Publish a draft type

    $ docutray types update invoice --publish

DOCUMENTATION
  Learn more: https://docs.docutray.com/cli/types/update

See code: src/commands/types/update.ts

Authentication

The CLI resolves the API key in this order:

1. Environment variable DOCUTRAY_API_KEY (recommended for CI/CD and AI agents)
2. Config file ~/.config/docutray/config.json (set via docutray login)

CI/CD and automation

# Set the env var in your CI pipeline
export DOCUTRAY_API_KEY=dt_live_abc123

# All commands will use it automatically
docutray convert invoice.pdf --type electronic-invoice

AI coding agents (Claude Code, Cursor, Codex)

When the CLI runs inside an agent, stdin is not a TTY and the interactive prompt is unreachable. Use --oauth to drive the full OAuth flow without a TTY: the CLI prints the authorization URL on stderr, opens your browser, and writes the resulting API key to ~/.config/docutray/config.json.

docutray login --oauth
# stderr → "Open this URL to authorize: https://app.docutray.com/oauth/..."
# (your browser opens; authorize there)
# stdout ← {"message":"Login successful","apiKey":"dt_live_****…","configPath":"…"}

docutray status
# {"authenticated": true, ...}

Use --no-browser to suppress the auto-open (the URL is still printed to stderr) and --timeout <seconds> to override the 180s default.

Multiple environments

# Use --base-url for staging or custom deployments
docutray login --base-url https://staging.docutray.com

Output format

• JSON by default — optimized for programmatic consumption by AI agents and scripts
• Human-friendly output in TTY — tables, key-value pairs, and icons when running interactively
• --json flag — force JSON output explicitly (automatic when stdout is piped)
• Exit code 0 — success
• Exit code 1 — error, with JSON error details on stderr

Piping and composition

# Extract specific fields with jq
docutray types list | jq '.data[].codeType'

# Chain commands
docutray identify document.pdf | jq -r '.document_type.code' | xargs -I{} docutray convert document.pdf -t {}

# Use in shell scripts
if docutray status | jq -e '.authenticated' > /dev/null 2>&1; then
  echo "Authenticated"
fi

Development

git clone https://github.com/docutray/docutray-cli.git
cd docutray-cli
npm install
npm run build
npm link

Scripts

npm run dev              # Watch mode for TypeScript compilation
npm run build            # Compile TypeScript
npm run test             # Run tests
npm run docs:generate    # Regenerate command reference docs

Documentation

• Authentication guide
• Document processing guide
• Document types guide
• AI agent usage guide
• Command reference

Links

• API Documentation
• Node SDK
• Dashboard