> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/processors.md).

# processors

Convert raw CSV, XML, and EDI text into JSON records, and back again, without touching account state. Processors are stateless transformation calls: you send bytes plus a rule set, and the platform returns the result. Nothing on the account is created or modified, so these commands work from a `read`-mode profile.

Use `parse edi` to validate a file definition before you build anything on it. Run a real partner file against the definition, then read the per-record validation failures from `recordLevelErrors`. That check costs one call and catches spec problems before an export, import, or flow depends on them.

**REST API**: [Parsers & Generators](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators)

```
celigo processors <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                          | Purpose                                                                                           |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `list`                              | List the processor catalog — parser/generator type names with their input and output media types. |
| `invoke <name>`                     | Call any catalog processor by name with a full JSON request body (`--file <path>` or stdin).      |
| `parse <csv\|edi\|xml> [dataFile]`  | Parse raw data into JSON records. Reads the file at `[dataFile]`, or stdin.                       |
| `generate <csv\|edi> [recordsFile]` | Generate formatted text from a JSON array of records. Reads `[recordsFile]`, or stdin.            |

***

## `celigo processors list`

List the processor catalog. The API returns an object keyed by processor name. The CLI flattens it into a sorted array of rows, so `--format table` and `--jq` behave as they do on every other list command. Default table columns: `name`, `label`, `dataMediaType`, `resultMediaType`.

Use `list` to discover valid `invoke <name>` values.

**Signature**

```bash
celigo processors list
```

**Arguments**

None.

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo processors list --format table
```

**Corresponds to**: [`GET /v1/processors`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators)

***

## `celigo processors invoke`

Call any processor in the catalog by name, supplying the complete JSON request body yourself. Use `invoke` for processors that `parse` and `generate` do not wrap, or when you need exact control over `rules` and `options`.

The CLI passes `<name>` into the endpoint path verbatim and does not validate it against a fixed list, so any name from `processors list` works. The common ones are `csvParser`, `csvDataGenerator`, `structuredFileParser`, `structuredFileGenerator`, and `xmlParser`.

**Signature**

```bash
celigo processors invoke <name> --file <path>
celigo processors invoke <name> < body.json     # or pipe on stdin
```

**Arguments**

| Argument | Type   | Required | Description                                                                       |
| -------- | ------ | -------- | --------------------------------------------------------------------------------- |
| `<name>` | string | Yes      | Processor name from `processors list` (e.g. `csvParser`, `structuredFileParser`). |

**Flags**

| Flag                | Type   | Default | Description                                                                    |
| ------------------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `-f, --file <path>` | string | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). |

**Request body**

A JSON object matching the processor's own request schema. Parsers take the raw text in `data` and the rule set in `rules`; generators take an array of records in `data`. An optional `options` object carries extras such as `includeEmptyValues` or an `ediProfile` envelope block.

```json
{
  "data": "a,b\n1,2",
  "rules": { "columnDelimiter": ",", "hasHeaderRow": true }
}
```

**Example**

```bash
echo '{"data":"a,b\n1,2","rules":{"columnDelimiter":",","hasHeaderRow":true}}' \
  | celigo processors invoke csvParser
```

**Corresponds to**: [`POST /v1/processors/{name}`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators)

***

## `celigo processors parse`

Parse raw data into JSON records. The first positional argument is the format — `csv`, `edi`, or `xml` — and it selects which processor endpoint the CLI calls. The raw input comes from the `[dataFile]` path, or from stdin when you omit the path or pass `-`.

The CLI sends the input bytes unaltered and never trims them. Row delimiters and segment terminators carry meaning in EDI and fixed-width data.

`edi` covers everything the structured-file parser handles: X12, EDIFACT, custom delimited, and fixed-width. Use it to validate a partner file against a spec.

**Signature**

```bash
celigo processors parse <csv|edi|xml> [dataFile] [flags]
celigo processors parse <csv|edi|xml> < data.txt        # or pipe on stdin
```

**Arguments**

| Argument     | Type                    | Required | Description                                                              |
| ------------ | ----------------------- | -------- | ------------------------------------------------------------------------ |
| `<format>`   | `csv` \| `edi` \| `xml` | Yes      | Input format to parse into JSON records. Selects the processor endpoint. |
| `[dataFile]` | string                  | No       | Path to the raw input file. Omit it, or pass `-`, to read stdin.         |

**Flags**

Each flag applies to specific formats only, named in bold at the start of its description. Passing a flag that does not apply to the chosen format is an error, not a no-op. See the gotchas below.

| Flag                        | Type    | Default | Description                                                                                                                                                            |
| --------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--rules <path>`            | string  | —       | **csv, xml** — full parsing-rules JSON file. Sent as `rules` verbatim, replacing the convenience flags below.                                                          |
| `--file-definition-id <id>` | string  | —       | **edi** — parse using a saved [file definition](/cli/commands/file-definitions.md) by ID. Sent as `rules._fileDefinitionId`.                                           |
| `--file-definition <path>`  | string  | —       | **edi** — parse using an inline file definition JSON file. Sent as `rules.fileDefinition`.                                                                             |
| `--resource-path <path>`    | string  | —       | **edi, xml** — for `xml`, the XPath to the repeating element (e.g. `/root/item`); for `edi`, a dot path selecting the segment to return. Sent as `rules.resourcePath`. |
| `--edi-profile-id <id>`     | string  | —       | **edi** — the CLI fetches that [EDI profile](/cli/commands/edi-profiles.md) resource and sends it as `options.ediProfile` for ISA/GS envelope context.                 |
| `--column-delimiter <char>` | string  | —       | **csv** — column delimiter.                                                                                                                                            |
| `--row-delimiter <char>`    | string  | —       | **csv** — row delimiter.                                                                                                                                               |
| `--has-header-row`          | boolean | `false` | **csv** — treat the first row as column headers.                                                                                                                       |
| `--trim-spaces`             | boolean | `false` | **csv** — trim leading and trailing spaces from values.                                                                                                                |
| `--rows-to-skip <n>`        | integer | —       | **csv** — number of rows to skip before parsing.                                                                                                                       |
| `--include-empty-values`    | boolean | `false` | **csv** — return empty values as `null` instead of omitting the key. Sent as `options.includeEmptyValues`, not inside `rules`.                                         |

Rule requirements differ by format. `csv` needs no rule flags: every rules field is optional, so `parse csv ./data.csv` parses with server defaults. `xml` requires either `--resource-path` or `--rules`. `edi` requires exactly one of `--file-definition-id` or `--file-definition`. Passing both, or neither, fails before any request is sent.

**Request body**

The CLI assembles the body: the raw input goes in `data` and the resolved rule set in `rules`. For `edi`, the definition is wrapped inside `rules`, as either `rules._fileDefinitionId` or `rules.fileDefinition`:

```json
{
  "data": "ISA*00*...~\nGS*PO*...~\nST*850*0001~\n...",
  "rules": { "_fileDefinitionId": "5f83a9b2c7d3e8f1a2b3c4d5" }
}
```

**Examples**

```bash
# CSV from a file, first row is headers
celigo processors parse csv ./orders.csv --column-delimiter , --has-header-row

# XML from stdin, one record per <item>
cat ./catalog.xml | celigo processors parse xml --resource-path /catalog/item

# Validate a real partner file against a saved X12 definition before building the flow
celigo processors parse edi ./po_850.edi \
  --file-definition-id 5f83a9b2c7d3e8f1a2b3c4d5 \
  --edi-profile-id 60a1b2c3d4e5f6a7b8c9d0e1 \
  --jq '.recordLevelErrors'

# Same check with a definition you haven't saved to the account yet
celigo processors parse edi ./po_850.edi --file-definition ./x12-850.json
```

**Corresponds to**: [`POST /v1/processors/csvParser`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) for `csv`, [`POST /v1/processors/xmlParser`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) for `xml`, and [`POST /v1/processors/structuredFileParser`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) for `edi`. `--edi-profile-id` first issues an internal `GET /v1/ediprofiles/{_id}` to fetch the profile it embeds.

***

## `celigo processors generate`

Generate formatted output from JSON records — the reverse of `parse`. The first positional argument is the format, either `csv` or `edi`. The input is a JSON array read from `[recordsFile]` or stdin, and each element of the array is one document to generate. The CLI rejects a non-array input before any request is made.

The generated text arrives inside a JSON response. Pipe it through `--jq .data` to write the raw file.

**Signature**

```bash
celigo processors generate <csv|edi> [recordsFile] [flags]
celigo processors generate <csv|edi> < records.json     # or pipe on stdin
```

**Arguments**

| Argument        | Type           | Required | Description                                                           |
| --------------- | -------------- | -------- | --------------------------------------------------------------------- |
| `<format>`      | `csv` \| `edi` | Yes      | Output format to generate. Selects the processor endpoint.            |
| `[recordsFile]` | string         | No       | Path to a JSON array of records. Omit it, or pass `-`, to read stdin. |

**Flags**

| Flag                        | Type    | Default | Description                                                                                                                                            |
| --------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--rules <path>`            | string  | —       | **csv** — full generation-rules JSON file. Sent as `rules` verbatim, replacing the convenience flags below.                                            |
| `--file-definition <path>`  | string  | —       | **edi** — required. The generation rules JSON, sent **directly** as `rules` with no wrapper.                                                           |
| `--edi-profile-id <id>`     | string  | —       | **edi** — the CLI fetches that [EDI profile](/cli/commands/edi-profiles.md) resource and sends it as `options.ediProfile` for ISA/GS envelope context. |
| `--column-delimiter <char>` | string  | —       | **csv** — column delimiter.                                                                                                                            |
| `--row-delimiter <char>`    | string  | —       | **csv** — row delimiter.                                                                                                                               |
| `--include-header`          | boolean | `false` | **csv** — emit a leading header row of column names.                                                                                                   |
| `--wrap-with-quotes`        | boolean | `false` | **csv** — wrap every value in double quotes.                                                                                                           |

`generate` has no `--file-definition-id` and no `--resource-path`. EDI generation accepts an inline definition only.

**Request body**

The records array goes in `data` and the resolved rule set in `rules`. For `csv`, `rules` holds the delimiter and header settings. For `edi`, the file definition document is the `rules` object itself. There is no `fileDefinition` key, so the definition's own `format`, delimiter block, and nested `rules` array all sit one level up:

```json
{
  "data": [{ "orderId": "4500012345", "sku": "WIDGET-01", "qty": 10 }],
  "rules": {
    "format": "delimited",
    "delimited": { "rowDelimiter": "\n", "colDelimiter": "*" },
    "rules": []
  }
}
```

**Examples**

```bash
# CSV with a header row, written to a file
echo '[{"orderId":"4500012345","sku":"WIDGET-01","qty":10}]' \
  | celigo processors generate csv --include-header --jq .data > orders.csv

# X12 850 from records, enveloped with a saved partner profile
celigo processors generate edi ./records.json \
  --file-definition ./x12-850-generate.json \
  --edi-profile-id 60a1b2c3d4e5f6a7b8c9d0e1 \
  --jq .data > po_850.edi
```

**Corresponds to**: [`POST /v1/processors/csvDataGenerator`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) for `csv` and [`POST /v1/processors/structuredFileGenerator`](https://developer.celigo.com/api/api-reference/b2b-manager/parsers-and-generators) for `edi`. `--edi-profile-id` first issues an internal `GET /v1/ediprofiles/{_id}` to fetch the profile it embeds.

***

## Gotchas

* **Every processor command works in a `read`-mode profile, even though the HTTP verb is `POST`.** A `read`-mode profile normally blocks `POST` before the request leaves your machine. `/v1/processors/*` is on the client's read-only allowlist because these calls are pure transforms. Nothing on the account can be created, run, or changed. You can point `processors` at a production account from a locked-down profile. Other read-only `POST` paths are allowlisted the same way, including export previews and connection pings — see [Profiles & regions](/cli/getting-started/profiles.md#permission-modes).
* **A `200 OK` response does not mean every record parsed.** For `parse edi`, per-record validation failures come back in `recordLevelErrors` alongside the records that parsed. The HTTP call still succeeds and the exit code is still `0`. Inspect `recordLevelErrors` directly, for example with `--jq '.recordLevelErrors'`.
* **The parser wraps the definition; the generator does not.** `parse edi` nests the definition inside `rules`, as `rules._fileDefinitionId` for a saved definition or `rules.fileDefinition` for an inline one. `generate edi` sends the definition's fields as `rules` itself. The two request shapes are not interchangeable. A JSON file that works with one fails with the other.
* **`generate edi` requires an inline definition, even when that definition is saved on the account.** Generation has no `--file-definition-id`, because the API accepts an inline rule set only. Fetch the saved resource with `celigo file-definitions get <id>`, write the definition fields to a local file, then pass that file to `--file-definition`.
* **A flag for the wrong format is rejected, not ignored.** All format flags live on one command, so the CLI checks applicability before doing any work. It fails with `Option(s) not applicable to format '<format>': <flags>` and names each misapplied flag. `--has-header-row` on `parse edi` and `--edi-profile-id` on `generate csv` both stop the command.
* **`--rules` supersedes the individual rule flags.** With `--rules <path>` present, the file becomes the entire `rules` object. `--column-delimiter`, `--has-header-row`, and `--resource-path` then have no effect. `--include-empty-values` is the exception: it travels in `options` rather than `rules`, so it still applies.
* **Use `--jq .data` to extract raw text.** Generated output arrives wrapped in JSON, so redirecting the default output writes a JSON document rather than a usable file. `--jq .data > out.edi` writes the generated text itself.
* **stdin carries the data, not the rules.** `--rules`, `--file-definition`, and the other rule inputs require real file paths; passing `-` is rejected. Supply the payload as `[dataFile]` or `[recordsFile]` when you need stdin for something else. Only one input can come from stdin.
* **`generate` requires a JSON array.** A bare object is rejected with a message stating that each array element is one document. Wrap a single record as `[{ … }]`.

## Related

* [file-definitions](/cli/commands/file-definitions.md) — the saved parsing and generation rules that `--file-definition-id` references and `--file-definition` inlines.
* [edi-profiles](/cli/commands/edi-profiles.md) — the trading partner envelope configuration that `--edi-profile-id` supplies for ISA/GS context.
* [exports](/cli/commands/exports.md) — where a validated parsing rule set runs in production, on file-based exports.
* [imports](/cli/commands/imports.md) — where a validated generation rule set runs in production, producing outbound files.
* [edi-transactions](/cli/commands/edi-transactions.md) — the transaction log for documents exchanged once the flow is live.