> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run

> Run vision analysis on an image or PDF using docex.run() or the docex run CLI command.

# Run

> Run vision analysis on an image or PDF. The SDK handles upload, polling, and returns a structured envelope. The CLI is useful for one-off analysis and debugging.

## SDK

```js theme={null}
import { createDocex } from "docexdev";

const docex = createDocex({
  apiKey: process.env.DOCEX_API_KEY,
  baseUrl: process.env.DOCEX_BASE_URL,
});

const result = await docex.run({
  file: "./invoice.pdf",
  prompt: "Extract line items, totals, and vendor details",
  outputFormat: "json",     // optional, default: "json"
  schemaId: "invoice/global-accounts-payable",  // optional
  schema: undefined,        // optional inline schema
  workflow: "fast",         // optional
  metadata: { source: "uploads-api" },  // optional
});
```

### Parameters

| Parameter      | Type                           | Required | Description                                                               |
| -------------- | ------------------------------ | -------- | ------------------------------------------------------------------------- |
| `file`         | `string \| { fileName, data }` | Yes      | Local file path or object with `fileName` and `data` (Uint8Array/Buffer)  |
| `prompt`       | `string`                       | Yes      | Plain-English description of the analysis task                            |
| `outputFormat` | `"json" \| "text"`             | No       | Output format. Default: `"json"`                                          |
| `schemaId`     | `string`                       | No       | Built-in registry schema identifier                                       |
| `schema`       | `object`                       | No       | Inline custom schema with `label`, `expectedFields`, and `promptScaffold` |
| `workflow`     | `string`                       | No       | Optional workflow label for dashboard filtering                           |
| `metadata`     | `object`                       | No       | Arbitrary metadata attached to the job                                    |

### Response

The SDK polls automatically and returns the completed run envelope:

```json theme={null}
{
  "status": "completed",
  "result": { ... },
  "usage": { "requests": 1, "costUsd": 0.0321, "priceUsd": 0.0642 },
  "chargedUsd": 0.0642,
  "confidence": 0.95,
  "metadata": {}
}
```

## CLI

```bash theme={null}
# Analyze a local file
docex run invoice.pdf --prompt "Extract line items and totals"

# Specify output format
docex run screenshot.png --prompt "is_phishing, confidence_score" --format json

# Use a built-in schema
docex run license.heic --schema-id "trade-license/uae"

# Override env vars
docex run image.png --prompt "..." --api-key dx_live_... --base-url https://api.docex.dev
```