> 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/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/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/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/parsers-and-generators) for `csv`, [`POST /v1/processors/xmlParser`](https://developer.celigo.com/api/api-reference/parsers-and-generators) for `xml`, and [`POST /v1/processors/structuredFileParser`](https://developer.celigo.com/api/api-reference/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/parsers-and-generators) for `csv` and [`POST /v1/processors/structuredFileGenerator`](https://developer.celigo.com/api/api-reference/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/processors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.