---
title: "Turn documents into data your AI can use: PreciseMD parsing, NAS integration, and MCP/CLI"
description: "Four scenarios: parse uploaded files in Playground, connect a NAS for batch processing, let an AI agent call the tools over MCP, and wire parsing into scripts and schedules with the CLI"
canonical_url: "https://docs.ardge.com/en/knowledge/precisemd/mcp-cli-integration"
---
# Turn documents into data your AI can use: PreciseMD parsing, NAS integration, and MCP/CLI

> Four scenarios: parse uploaded files in Playground, connect a NAS for batch processing, let an AI agent call the tools over MCP, and wire parsing into scripts and schedules with the CLI

## Overview

PreciseMD is the document parsing application on the ARX platform. It extracts the text and the charts inside images, PDFs, Excel files, and PowerPoint decks accurately, turning them into data an AI knowledge base can use directly.

A knowledge base is only as good as the precision of its source data: the more complete the parsing, the less likely the AI is to go wrong when searching and generating answers, and the more reliably employees and customers find correct information.

This article covers four scenarios. They're independent — read the ones you need:

- **Scenario 1 · Parse uploaded files**: send documents into PreciseMD and get structured text and images back
- **Scenario 2 · Connect a NAS**: connect your existing file system and batch process the documents already there
- **Scenario 3 · MCP integration**: let an AI agent discover and call PreciseMD's tools on its own
- **Scenario 4 · CLI integration**: wire parsing into scripts, schedules, or CI pipelines

## Applies to

- ARX OS 1.0 and later
- PreciseMD 1.0 and later

## Before you begin

Confirm both of the following:

- PreciseMD is installed from App Market
- Your account has access to PreciseMD, so the application appears on your desktop

---

## Scenario 1. Parse uploaded files and get structured text and images

This scenario suits having a handful of files on hand and wanting to check the parsing quality first. The whole flow happens on the Playground page, with nothing to configure.

### 1. Upload files

1. Open PreciseMD and go to the Playground page
2. Click the Upload button in the "Source Documents" section
3. Select the files to parse, or drag them onto the drop area
4. Click upload

> **Supported formats**: PDF, JPG, PNG, WEBP, BMP, TIFF, DOCX, XLSX, PPTX
> **Per-upload limit**: 100 files

### 2. Run the parsing

1. In the "Source Documents" section, select the files to parse
2. Click the "RUN" button below to start parsing

#### Complex documents: turn on advanced visual parsing

Documents with complex layout — financial statements, import customs declarations — can use **advanced visual parsing**. The system re-checks the parsing result through a vision model, which improves accuracy.

Once it's on, you can add a text parsing prompt describing the document's layout, or naming the fields that need particular attention. The more specific the prompt, the closer the corrected result is to what you actually need.

> ⚠️ **It adds to the parsing time**
> With it on, each page takes roughly 5 seconds longer — allow for that when the file volume is large.

### 3. Review the parsing result

1. In the "Run History" section, click the file you want to review
2. A dialog opens, offering four ways to view it:

- **Original**: the source file as it is
- **Bounding Box**: the parsed regions outlined on the original file
- **Preview**: the parsed Markdown document, rendered
- **Markdown**: the parsing result as Markdown source

---

## Scenario 2. Connect a NAS and set up a batch parsing task for the documents you already have

When your company documents already sit on a NAS, there's no need to upload them one by one. PreciseMD connects to the NAS over SMB to read the files directly and writes the parsing results into another folder you specify; the original data stays untouched, and the knowledge base's source data is built at the same time.

### 1. Set up the NAS connection

1. Open PreciseMD and go to Data Source
2. Click the "Add Connection" button
3. Enter the connection name, the NAS IP, the username and password, and select a Shared folder

### 2. Create the parsing task

1. Open PreciseMD and go to Task
2. Click the "Add Task" button
3. Set Task Name, Source Folder, and Target Folder

The fields mean:

- **Source Folder**: where the original data this task processes lives
- **Target Folder**: where the structured data goes after parsing
- **Scan Path**: how many folder levels down to scan
- **Model Connection**: the model this task uses; left empty, the system default model is used
- **VLM & Prompt**: set it the same way as [Complex documents: turn on advanced visual parsing](#complex-documents-turn-on-advanced-visual-parsing)

### 3. Run the parsing

1. Open PreciseMD and go to Task
2. On the row of the task to run, click the "Run" button to start parsing
3. Wait for that task row's Last Result to read Completed

---

## Scenario 3. An AI agent parses documents with PreciseMD over MCP

The first two scenarios are all human work in the web interface. To let an AI agent — Claude Code, Cursor, or one your company built — parse documents, manage data sources, and track batch tasks by itself, integrate those capabilities through PreciseMD's **HTTP MCP** interface.

Once integrated, the agent can use these 11 tools:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Permission level
    </th>
    
    <th>
      Data source restriction
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        arcor_system_version
      </code>
    </td>
    
    <td>
      Query the system version
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_list_capabilities
      </code>
    </td>
    
    <td>
      Query which tools the current PAT can use
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_run_ocr
      </code>
    </td>
    
    <td>
      Parse a single file
    </td>
    
    <td>
      Standard
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_run_batch_ocr
      </code>
    </td>
    
    <td>
      Run batch parsing against a data source
    </td>
    
    <td>
      Standard
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_get_job
      </code>
    </td>
    
    <td>
      Query a batch task's status and progress
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_cancel_job
      </code>
    </td>
    
    <td>
      Cancel a running batch task
    </td>
    
    <td>
      Destructive
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_create_datasource
      </code>
    </td>
    
    <td>
      Create an SMB data source
    </td>
    
    <td>
      Standard
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_list_datasources
      </code>
    </td>
    
    <td>
      List data sources
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_browse_datasource
      </code>
    </td>
    
    <td>
      Browse the files in a data source
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_delete_datasource
      </code>
    </td>
    
    <td>
      Delete a data source
    </td>
    
    <td>
      Destructive
    </td>
    
    <td>
      Restricted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        arcor_list_prompts
      </code>
    </td>
    
    <td>
      List the available parsing prompts
    </td>
    
    <td>
      Read-only
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

The permission level maps to the PAT's action scope: a read-only PAT can use only "Read-only" tools, and "Destructive" tools need a PAT that can delete. "Restricted" tools can operate only on the data sources the PAT is allowed to access, and list results show only those data sources.

> ⚠️ **Before you start, check the execution environment**
> Uploading a file goes through a REST endpoint, **not** an MCP tool call. The environment driving the agent has to be able to make HTTP requests (`curl`, Python `requests`, or a workflow engine's HTTP node all work).
> A pure chat interface that can't run code or send HTTP requests can't do single-file parsing at all, because no MCP tool takes file content directly.

### 1. Create a PAT for access

The MCP connection authenticates with a **PAT (personal access token)**. A system administrator creates PATs, and can create one for any user account; regular users can't create their own.

1. Open PreciseMD with an administrator account and go to the User Management page
2. In the Action column of the user you're authorizing, click "Manage personal access tokens"
3. In the "Personal Access Tokens" dialog, click the "Create" button
4. In the "Create Personal Access Token" dialog, set Name, Action Scope, Resource Scope, and Expires At (leave it empty for a token that never expires)
5. Take the generated token

> ⚠️ **Store the token immediately**
> As soon as the token is created, put it somewhere the agent can read at startup. Lose it and your only option is to create another.

Creating a PAT means deciding two kinds of scope:

- **Operation scope (Action Scope)**: which class of operations this PAT can perform — Read only, Read and write, or Read, write and delete
- **Data access scope (Resource Scope)**: which data sources this PAT can reach. Check "Grant all datasources" to cover every data source, present and future, or pick individual data sources; you have to select at least one, or the PAT can't be created

### 2. Configure the MCP server in your AI agent

Put these connection details into the agent's MCP configuration:

<table>
<thead>
  <tr>
    <th>
      Item
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Endpoint
    </td>
    
    <td>
      <code>
        <PRECISEMD_URL>/mcp
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Transport
    </td>
    
    <td>
      Streamable HTTP
    </td>
  </tr>
  
  <tr>
    <td>
      Authentication
    </td>
    
    <td>
      <code>
        Authorization: Bearer <YOUR_PAT>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Per-request limit
    </td>
    
    <td>
      256 KB (counting only the tool call's arguments — file content never goes through this endpoint)
    </td>
  </tr>
</tbody>
</table>

> 💡 **How to find <PRECISEMD_URL>**
> Go to the ARX desktop, right-click the PreciseMD icon, choose to open it in a new tab, and copy the scheme, host, and port from the address bar — for example, `http://192.168.1.20:30002`. Use it in place of every `<PRECISEMD_URL>` on this page.

For Claude Code, save the following as `.mcp.json` in the project root. The first time you start Claude Code in that project, it asks whether to enable this MCP server; choose to enable it.

```json
{
  "mcpServers": {
    "precisemd": {
      "type": "http",
      "url": "<PRECISEMD_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PAT>"
      }
    }
  }
}
```

#### Give your agent the PreciseMD MCP skill

The `precisemd-mcp` skill teaches the agent how to chain the tools: how to upload a file, how to poll a batch job, and what each error means. Each PreciseMD install serves the copy of the skill that matches its own version, with no authentication.

Set `SKILLS` to the directory your agent loads skills from: `~/.claude/skills` for Claude Code, `~/.agents/skills` for Codex, Cursor, and GitHub Copilot.

```bash
SKILLS=~/.claude/skills
curl -fSL -o /tmp/mcp.zip "<PRECISEMD_URL>/api/v1/skills/mcp.zip"
rm -rf "$SKILLS/precisemd-mcp"
mkdir -p "$SKILLS" && unzip /tmp/mcp.zip -d "$SKILLS"
```

On Windows, run these in PowerShell instead:

```powershell
$skills = "$HOME\.claude\skills"
Invoke-WebRequest -UseBasicParsing -Uri "<PRECISEMD_URL>/api/v1/skills/mcp.zip" -OutFile "$env:TEMP\mcp.zip"
Remove-Item -Recurse -Force "$skills\precisemd-mcp" -ErrorAction SilentlyContinue
Expand-Archive -Path "$env:TEMP\mcp.zip" -DestinationPath $skills
```

- **Claude Desktop and claude.ai**: upload `mcp.zip` as it is under **Customize > Skills** — don't extract it first
- **An agent you built yourself**: extract the zip and have the agent read `precisemd-mcp/SKILL.md`; the files it refers to are all inside the `precisemd-mcp/` folder

> ⚠️ **Don't use File Explorer's "Extract All"**
> The zip holds a single `precisemd-mcp/` folder, and the agent looks for that folder directly inside the skills directory. "Extract All" wraps it in an extra folder named after the zip, and the agent can't load the skill.

> 💡 **Download the skill again after you upgrade PreciseMD**
> The commands above delete the old folder before extracting, so files the new version dropped don't linger. If extracting fails because the file isn't a zip archive, your PreciseMD install doesn't offer this download yet.

### 3. Upload a file and run the parsing

An MCP request is capped at 256 KB, so **file content doesn't travel through the MCP channel**. It's uploaded through a separate REST endpoint instead, and the credential you get back is handed to the tool.

<table>
<thead>
  <tr>
    <th>
      Item
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Upload endpoint
    </td>
    
    <td>
      <code>
        POST /api/v1/mcp/uploads
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Authentication
    </td>
    
    <td>
      The same PAT as the MCP connection (a Read only PAT can't upload and gets a 403)
    </td>
  </tr>
  
  <tr>
    <td>
      File size limit
    </td>
    
    <td>
      100 MB
    </td>
  </tr>
  
  <tr>
    <td>
      Supported formats
    </td>
    
    <td>
      PDF, JPG, PNG, WEBP, BMP, TIFF
    </td>
  </tr>
  
  <tr>
    <td>
      Content type
    </td>
    
    <td>
      <code>
        application/octet-stream
      </code>
      
       (send the file content directly), or <code>
        multipart/form-data
      </code>
      
       (field name <code>
        file
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

An upload example:

```bash
curl -X POST <PRECISEMD_URL>/api/v1/mcp/uploads \
  -H "Authorization: Bearer <YOUR_PAT>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @invoice.pdf
```

Hand the response's `data.uploadToken` to `arcor_run_ocr` and the agent gets the parsed Markdown. An `uploadToken` works only once, and expires after about 15 minutes if unused. The two flows are:

**Single-file parsing**: upload the file (REST) → `arcor_run_ocr` (MCP) → get the Markdown

**Batch parsing** (no upload needed): `arcor_list_datasources` → `arcor_browse_datasource` → `arcor_run_batch_ocr` → poll `arcor_get_job`

In batch parsing, the source and target paths are relative to the shared folder's root, with no leading `/` — for example, `invoices/2026`. The target folder must already exist; the MCP tools don't create it.

---

## Scenario 4. An AI agent parses documents with PreciseMD over the CLI

The CLI is a single executable, suited to scripts, scheduled tasks, CI pipelines, or an agent with shell access issuing commands directly. It's designed for automation: every command supports `--json` output and classifies errors by exit code, so a program can decide what to do next.

The commands at a glance:

<table>
<thead>
  <tr>
    <th>
      Group
    </th>
    
    <th>
      Commands
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Authentication
    </td>
    
    <td>
      <code>
        auth login｜status｜logout
      </code>
      
      , <code>
        health
      </code>
      
      , <code>
        version
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Single-file parsing
    </td>
    
    <td>
      <code>
        ocr <file>
      </code>
      
      , <code>
        ocr result <id>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Data sources
    </td>
    
    <td>
      <code>
        ds create｜list｜get｜update｜delete
      </code>
      
      , <code>
        ds browse｜upload｜download
      </code>
      
      , <code>
        ds create-dir｜test-connection
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Tasks
    </td>
    
    <td>
      <code>
        task create｜list｜get｜update｜delete
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Jobs
    </td>
    
    <td>
      <code>
        job trigger｜list｜status｜logs｜cancel
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Prompt templates
    </td>
    
    <td>
      <code>
        prompt-template create｜list｜get｜update｜delete
      </code>
      
       (abbreviated as <code>
        pt
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Playground
    </td>
    
    <td>
      <code>
        playground quick-upload｜quick-run
      </code>
      
      , <code>
        playground workspace …
      </code>
    </td>
  </tr>
</tbody>
</table>

Common parameters: `--server <url>`, `--json`, `--token <PAT>`, `--config <path>`, `--fields <field list>`

### 1. Install the CLI

The PreciseMD server serves the executable itself — no external package registry needed. These commands install it to `~/.local/bin`, with no sudo required:

```bash
export ARCOR_SERVER="<PRECISEMD_URL>"

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH="amd64"; [ "$ARCH" = "aarch64" ] && ARCH="arm64"
mkdir -p "$HOME/.local/bin"
curl -fSL -o "$HOME/.local/bin/arcor" \
  "${ARCOR_SERVER}/api/v1/cli/download?os=${OS}&arch=${ARCH}"
chmod +x "$HOME/.local/bin/arcor"
export PATH="$HOME/.local/bin:$PATH"
arcor version
```

The server provides executables for Linux (amd64, arm64), macOS (Apple Silicon, arm64), and Windows (amd64). There is no build for Intel Macs. On Windows, open `<PRECISEMD_URL>/api/v1/cli/download?os=windows&arch=amd64` in a browser instead to download `arcor.exe`.

#### Give your agent the PreciseMD CLI skill

When an agent drives the CLI, the `precisemd-cli` skill teaches it the common commands and flags, and what each exit code means. The skill is named `precisemd-cli`, but the command is still `arcor`, the config file is still in `~/.arcor/`, and the environment variables are still `ARCOR_SERVER` and `ARCOR_TOKEN`. Each PreciseMD install serves the copy of the skill that matches its own version, with no authentication.

Set `SKILLS` to the directory your agent loads skills from: `~/.claude/skills` for Claude Code, `~/.agents/skills` for Codex, Cursor, and GitHub Copilot. The commands use the `ARCOR_SERVER` set above.

```bash
SKILLS=~/.claude/skills
curl -fSL -o /tmp/cli.zip "${ARCOR_SERVER}/api/v1/skills/cli.zip"
rm -rf "$SKILLS/precisemd-cli"
mkdir -p "$SKILLS" && unzip /tmp/cli.zip -d "$SKILLS"
```

On Windows, set `ARCOR_SERVER` in PowerShell first (`$env:ARCOR_SERVER = "<PRECISEMD_URL>"`), then run:

```powershell
$skills = "$HOME\.claude\skills"
Invoke-WebRequest -UseBasicParsing -Uri "${env:ARCOR_SERVER}/api/v1/skills/cli.zip" -OutFile "$env:TEMP\cli.zip"
Remove-Item -Recurse -Force "$skills\precisemd-cli" -ErrorAction SilentlyContinue
Expand-Archive -Path "$env:TEMP\cli.zip" -DestinationPath $skills
```

- **Claude Desktop and claude.ai**: upload `cli.zip` as it is under **Customize > Skills** — don't extract it first
- **An agent you built yourself**: extract the zip and have the agent read `precisemd-cli/SKILL.md`; the files it refers to are all inside the `precisemd-cli/` folder

> ⚠️ **Don't use File Explorer's "Extract All"**
> The zip holds a single `precisemd-cli/` folder, and the agent looks for that folder directly inside the skills directory. "Extract All" wraps it in an extra folder named after the zip, and the agent can't load the skill.

> 💡 **Download the skill again after you upgrade PreciseMD**
> The commands above delete the old folder before extracting, so files the new version dropped don't linger. If extracting fails because the file isn't a zip archive, your PreciseMD install doesn't offer this download yet.

### 2. Sign in for access

The CLI authenticates with a PAT. Create one the same way as in Scenario 3 — see [Create a PAT for access](#1-create-a-pat-for-access).

```bash
# Store the PAT (this non-interactive form is the one to use for automation)
arcor auth login --server <PRECISEMD_URL> --token <YOUR_PAT>

# Or pipe it in, to keep the token out of your command history
echo <YOUR_PAT> | arcor auth login --server <PRECISEMD_URL>

# Or just set the environment variable, writing nothing to disk
export ARCOR_TOKEN=<YOUR_PAT>
```

Then verify:

```bash
arcor auth status    # confirm the PAT is still valid
arcor health         # confirm the server connection is fine
```

- The config file lives at `~/.arcor/config.yaml` (mode 0600); `--config` points at another path
- After a successful sign-in, later commands no longer need `--server`
- `arcor auth logout` only clears the locally stored PAT — it does **not** revoke it on the server

### 3. Parse a single file

```bash
arcor ocr invoice.pdf                       # print the Markdown directly
arcor ocr invoice.pdf --output result.md    # write to a file
arcor ocr invoice.pdf --json                # print the full structured JSON
arcor ocr invoice.pdf --timeout 15m         # custom wait cap (10 minutes by default)
arcor ocr invoice.pdf --async               # return a runId immediately, without waiting
arcor ocr result <runId>                    # retrieve the result later
arcor ocr invoice.pdf --vlm --prompt "..."  # turn on advanced visual parsing with a parsing prompt
```

`arcor ocr` handles the upload, the run, the polling, and the output automatically — the most direct way to parse a single file. Add `--quiet` to turn off progress messages, which makes the output easier for a program to parse.

> `arcor ocr` supports PDF, JPG, PNG, WebP, BMP, and TIFF. For Office formats (DOCX, XLSX, PPTX), use the web interface instead.

### 4. Batch parsing

Batch parsing is made of three objects: a **data source** (where the files are), a **task** (how they're processed), and a **job** (one actual run).

#### Create the source and target data sources

```bash
arcor ds create --name "invoices-in" --scheme smb \
  --ip 192.168.1.10 --user svc --password '***' --share invoices-in

arcor ds create --name "invoices-out" --scheme smb \
  --ip 192.168.1.10 --user svc --password '***' --share invoices-out
```

The returned IDs are used in the next step; pull them out with `--json | jq -r '.id'`.

> ⚠️ **Only remote data sources can be created**
> SMB, for instance. Local file system data sources are managed by the system, and creating one yourself returns 403.

#### Create the task

```bash
arcor task create \
  --name "invoice-ocr" \
  --prompt "Convert to Markdown faithfully" \
  --source-datasource-id <source ID> --source-path "." \
  --target-datasource-id <target ID> --target-path "." \
  --enable-vlm \
  --scan-depth 2
```

- `--source-path` / `--target-path`: a path relative to the shared folder's root, with no leading `/`; `.` means the root itself. The target folder must already exist — create it with `arcor ds create-dir <target ID> --path <path>`
- `--prompt`: must be used with `--enable-vlm`, or it's rejected
- `--enable-vlm`: turns on advanced visual parsing. It takes longer and gives better quality
- `--scan-depth`: how many folder levels to scan. `1` processes only the source folder itself, `2` goes one level further down, and so on; left unset or set to `0` or below, it scans 10 levels

#### Run and monitor

```bash
arcor job trigger <taskId>                # trigger the task, returns a jobId (JSON field: id)
arcor job status <jobId>                  # query the overall progress once
arcor job logs <jobId>                    # each file's result
arcor job logs <jobId> --status running   # which file is being processed right now
arcor job logs <jobId> --status failed    # only the failed files
```

#### How output files are named

Each page of a PDF or image produces one `.md` and one `.jpg`; DOCX and PPTX produce only `.md`:

```text
report.pdf            → report_pdf_page_001.md, report_pdf_page_001.jpg
sub/dir/invoice.pdf   → sub/dir/invoice_pdf_page_001.md, …
```

The format is `{name}_{extension}_page_{number}.md`, and the target folder preserves the source's subdirectory structure. Images inside a page — product photos, charts — are saved into an `imgs/` folder alongside them, referenced from the Markdown as `<img src="imgs/…">`.

Every `.md` file opens with YAML frontmatter recording the source path, the page number, the processing time, whether VLM was on, the file hash, and more, which makes it straightforward for a downstream RAG system to index.

Verify the output:

```bash
arcor ds browse <target ID> --path "." --json | jq '.items[].name'
```

### 5. What to watch for in automation

Errors are classified by exit code, so a script can decide what to do next:

<table>
<thead>
  <tr>
    <th>
      Exit code
    </th>
    
    <th>
      What it means
    </th>
    
    <th>
      What to do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        0
      </code>
    </td>
    
    <td>
      Success
    </td>
    
    <td>
      —
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      Argument or input error
    </td>
    
    <td>
      Check the arguments with <code>
        <command> --help
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        2
      </code>
    </td>
    
    <td>
      Authentication failure (401/403)
    </td>
    
    <td>
      <strong>
        Don't retry automatically.
      </strong>
      
       The PAT has expired or lacks permissions — get a new PAT and run <code>
        arcor auth login
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        3
      </code>
    </td>
    
    <td>
      Server error (5xx)
    </td>
    
    <td>
      Retry after a delay
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        4
      </code>
    </td>
    
    <td>
      Network error (server unreachable, request timeout)
    </td>
    
    <td>
      Check the server address, retry with a backoff
    </td>
  </tr>
</tbody>
</table>

When `arcor ocr` waits past `--timeout`, it returns `1`, and the error message includes `arcor ocr result <runId>`. Run that to pick up the result without uploading again.

When an agent uses the CLI, keep to the following:

- **Always pass --json**: table output is for humans, and a program can't parse it reliably
- **Narrow the output with --fields**: `--fields id,name,status`, for example — taking only what you need saves context
- **There is no --dry-run**: `create` / `update` / `delete` take effect immediately. Confirm the target with `get <id>` before you change or delete anything
- **Don't mix --from-json with individual parameters**: the CLI rejects that combination outright


## Sitemap

See the full [sitemap](https://docs.ardge.com/sitemap.md) for all pages.