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

celigo processors <subcommand> [args] [flags]

Supports all global flags.

---

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

celigo processors list

Arguments

None.

Flags

Uses global flags only.

Example

celigo processors list --format table

Corresponds to: GET /v1/processors

---

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

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.

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

Example

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

Corresponds to: POST /v1/processors/{name}

---

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

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 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 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:

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

Examples

# 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 for csv, POST /v1/processors/xmlParser for xml, and POST /v1/processors/structuredFileParser 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

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 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:

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

Examples

# 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 for csv and POST /v1/processors/structuredFileGenerator 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.
• 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 — the saved parsing and generation rules that --file-definition-id references and --file-definition inlines.
• edi-profiles — the trading partner envelope configuration that --edi-profile-id supplies for ISA/GS context.
• exports — where a validated parsing rule set runs in production, on file-based exports.
• imports — where a validated generation rule set runs in production, producing outbound files.
• edi-transactions — the transaction log for documents exchanged once the flow is live.