> 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/file-definition-rules.md).

# file-definition-rules

Generate EDI file definition rules from a specification PDF (X12 or EDIFACT). This is the scriptable form of what the Ora agent does interactively, for onboarding trading partners in bulk. The API is asynchronous: you submit a PDF, the platform queues a job, and the command polls until the job completes. Nothing is persisted — a completed job returns rules JSON, and you save it yourself by piping it into [`file-definitions create`](/cli/commands/file-definitions.md#celigo-file-definitions-create).

The endpoints behind this group (`GET /v1/filedefinitionrules/document-types`, `POST /v1/filedefinitionrules/generate`, `POST /v1/filedefinitionrules/parse`, and `GET /v1/filedefinitionrules/{generate|parse}/{requestId}`) are not yet in the published API reference.

Added in celigo-cli 2026.9.1.

```
celigo file-definition-rules <subcommand> [args] [flags]
```

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

***

## Subcommands

| Subcommand           | Purpose                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------- |
| `document-types`     | List the X12 transaction set numbers the generator supports.                            |
| `generate <pdf>`     | Submit a specification PDF and return both artifacts: `generationFdr` and `parsingFdr`. |
| `parse <pdf>`        | Submit a specification PDF and return the parsing artifact only (`parsingFdr`).         |
| `status <requestId>` | Show the state of a submitted job, optionally waiting for it to finish.                 |

> **Submissions are capped at 10 per hour per account** (administrators bypass the cap). Jobs take one to several minutes. Run `document-types` before you submit: an unsupported document type still spends one of the 10 hourly submissions. Job records expire 24 hours after submission.

***

## `celigo file-definition-rules document-types`

List the X12 transaction set numbers the rule generator supports. Check this list before submitting a specification, because a submission for an unsupported type is rejected by the service only after it has counted against the hourly cap.

Works in `read` mode.

**Signature**

```bash
celigo file-definition-rules document-types
```

**Arguments**

None.

**Flags**

None beyond the [global flags](/cli/getting-started/global-flags.md).

**Example**

```bash
celigo file-definition-rules document-types

# Is 850 supported?
celigo file-definition-rules document-types --jq '.supportedTypes | any(. == 850)'
```

The output is `{"supportedTypes": [<n>, …], "edifactSupported": <boolean>}`. `supportedTypes` holds the X12 transaction set numbers; `edifactSupported` says whether `--document-type 0` (EDIFACT auto-detection) is available.

**Corresponds to**: `GET /v1/filedefinitionrules/document-types` (not yet in the published API reference).

***

## `celigo file-definition-rules generate`

Submit an EDI specification PDF and return both artifacts. The command waits for the job to finish, then prints the rules JSON:

* `generationFdr` — a complete file definition body. Pipe it into `file-definitions create` (after adding a `globalId`, see below) to create the definition that generates outbound documents.
* `parsingFdr` — wrapped as `{"resourcePath": …, "fileDefinition": {…}}` for embedding in an export or import. To create it as a standalone definition, take `.parsingFdr.fileDefinition`.

Prefer `generate` over `parse` when you may also need to send the document: both artifacts come from one submission against the shared hourly cap.

Before anything is sent, the CLI refuses what the service would reject: a missing or non-PDF file, a file over the 50 MB limit (measured on the base64-encoded upload, as the service measures it), and a document type outside the live `document-types` catalog (when the catalog cannot be read, the command warns and proceeds). The submit request gets the long-request timeout, so a large upload is never retried into the cap.

**Required:** `operate` or `full` mode — the submission creates a job on the account, so `read` mode blocks it.

**Signature**

```bash
celigo file-definition-rules generate <pdf> --document-type <n> [--no-wait] [--timeout <seconds>]
```

**Arguments**

| Argument | Type   | Required | Description                                                                                                                                                                                                                     |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<pdf>`  | string | Yes      | Path to the specification PDF. The file must contain text: scanned or image-only PDFs fail with `PDF_EXTRACTION_FAILED`. Maximum 50 MB once base64-encoded. Since celigo-cli 2026.10.1 a leading `~` means your home directory. |

**Flags**

| Flag                  | Type    | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--document-type <n>` | string  | —       | **Required.** X12 transaction set number (for example `850`), or `0` to auto-detect an EDIFACT specification. Checked against `document-types` before the submission. Since celigo-cli 2026.10.1 it must be digits only: `850abc` is refused (`--document-type must be a non-negative integer (an X12 transaction set number such as 850, or 0 for EDIFACT). Got '850abc'.`) where earlier releases submitted it as `850`. |
| `--no-wait`           | boolean | `false` | Submit and print `{"requestId": "<id>"}` without polling. Check on the job later with `status <requestId>`.                                                                                                                                                                                                                                                                                                                |
| `--timeout <seconds>` | integer | `420`   | Maximum time to wait for the job to complete. The service's own job timeout is 360 seconds; the default leaves headroom for queue time. On expiry the command exits `1` and names the `status` command to run — the job may still finish. Since celigo-cli 2026.10.1 a value that is not a positive whole number (`-5`, `5m`) is refused before the PDF is submitted: `--timeout must be a positive integer (got '5m').`   |

**Example**

```bash
# Generate both artifacts for an X12 850 specification
celigo file-definition-rules generate spec.pdf --document-type 850

# Auto-detect an EDIFACT specification
celigo file-definition-rules generate orders-d96a.pdf --document-type 0

# Submit now, poll later
celigo file-definition-rules generate spec.pdf --document-type 850 --no-wait
```

Turn the result into a saved file definition. `file-definitions create` takes `.generationFdr`; the whole result, or `parsingFdr` as it is (the `{resourcePath, fileDefinition}` wrapper), is refused with a `422`. EDI definitions also need a `globalId` naming the standard document, which the generator does not emit — without it `file-definitions create` fails with `global_id_not_provided`. Copy one from an existing definition of the same type:

```bash
celigo file-definition-rules generate spec.pdf --document-type 850 --jq .generationFdr > fd.json
celigo file-definitions list --jq '[.[]|select(.format=="delimited/x12")]|.[0].globalId'
# add that globalId to fd.json, then:
cat fd.json | celigo file-definitions create
```

**Corresponds to**: `POST /v1/filedefinitionrules/generate`, then `GET /v1/filedefinitionrules/generate/{requestId}` until the job completes (not yet in the published API reference).

***

## `celigo file-definition-rules parse`

Submit an EDI specification PDF and return the parsing artifact only (`parsingFdr`, wrapped as `{"resourcePath": …, "fileDefinition": {…}}`). The command waits for the job to finish, then prints the rules JSON. The same local checks, cap, and timeout rules as `generate` apply.

Use `parse` when you only receive the document. When you may also need to send it, use `generate`: it returns both artifacts from one submission.

**Required:** `operate` or `full` mode — the submission creates a job on the account, so `read` mode blocks it.

**Signature**

```bash
celigo file-definition-rules parse <pdf> --document-type <n> [--no-wait] [--timeout <seconds>]
```

**Arguments**

| Argument | Type   | Required | Description                                                                             |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `<pdf>`  | string | Yes      | Path to the specification PDF. Text-based PDFs only; maximum 50 MB once base64-encoded. |

**Flags**

| Flag                  | Type    | Default | Description                                                                                                                                                              |
| --------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--document-type <n>` | string  | —       | **Required.** X12 transaction set number (for example `850`), or `0` to auto-detect an EDIFACT specification. Digits only since celigo-cli 2026.10.1, as for `generate`. |
| `--no-wait`           | boolean | `false` | Submit and print the `requestId` without polling.                                                                                                                        |
| `--timeout <seconds>` | integer | `420`   | Maximum time to wait for the job to complete. A positive whole number since celigo-cli 2026.10.1, as for `generate`.                                                     |

**Example**

```bash
# Parsing rules only, as a standalone file definition body
celigo file-definition-rules parse spec.pdf --document-type 810 --jq .parsingFdr.fileDefinition > parse-fd.json
```

**Corresponds to**: `POST /v1/filedefinitionrules/parse`, then `GET /v1/filedefinitionrules/parse/{requestId}` until the job completes (not yet in the published API reference).

***

## `celigo file-definition-rules status`

Show the current state of a submitted rule generation job — the follow-up to a `generate --no-wait` or `parse --no-wait`. Without `--wait` the command prints the job record: `requestId`, `status` (`queued`, `processing`, `completed`, or `failed`), its timestamps, and `result` or `error` once the job has ended. With `--wait` it polls until the job completes or fails, then prints the rules JSON exactly as `generate`/`parse` do; a failed job exits `1` with the error code and message.

Works in `read` mode.

**Signature**

```bash
celigo file-definition-rules status <requestId> [--type <operation>] [--wait] [--timeout <seconds>]
```

**Arguments**

| Argument      | Type   | Required | Description                                                                                                         |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `<requestId>` | string | Yes      | The `requestId` printed by `generate --no-wait` or `parse --no-wait`. Job records expire 24 hours after submission. |

**Flags**

| Flag                  | Type                  | Default    | Description                                                                                                                                     |
| --------------------- | --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--type <operation>`  | `generate` \| `parse` | `generate` | Which job to poll. A `parse` submission is only found under `--type parse`.                                                                     |
| `--wait`              | boolean               | `false`    | Keep polling until the job completes or fails.                                                                                                  |
| `--timeout <seconds>` | integer               | `420`      | Maximum time to wait when `--wait` is set. Since celigo-cli 2026.10.1 it must be a positive whole number, and is checked even without `--wait`. |

**Example**

```bash
celigo file-definition-rules status 8f1c2d3e4a5b6c7d8e9f0a1b

# Block until a parse job finishes
celigo file-definition-rules status 8f1c2d3e4a5b6c7d8e9f0a1b --type parse --wait
```

**Corresponds to**: `GET /v1/filedefinitionrules/generate/{requestId}` or `GET /v1/filedefinitionrules/parse/{requestId}` (not yet in the published API reference).

***

## Gotchas

* **Nothing is saved.** Every subcommand prints JSON only. To keep the rules, pipe them into [`file-definitions create`](/cli/commands/file-definitions.md#celigo-file-definitions-create).
* **The two artifacts have different shapes.** `generationFdr` is a complete file definition body; `parsingFdr` is wrapped as `{resourcePath, fileDefinition}` for embedding in an export or import. Take `.parsingFdr.fileDefinition` to create the parsing rules standalone. `file-definitions create` refuses the whole result, or `parsingFdr` as it is, with a `422`.
* **`globalId` is not generated.** EDI file definitions require a `globalId` naming the standard document. Copy one from an existing definition of the same format (`celigo file-definitions list --jq '[.[]|select(.format=="delimited/x12")]|.[0].globalId'`), or `file-definitions create` fails with `global_id_not_provided`.
* **10 submissions per hour per account.** Administrators bypass the cap. Every `generate` or `parse` submission counts, including one the service rejects for an unsupported document type — check `document-types` first. The CLI refuses a missing or non-PDF file, a file over the 50 MB limit (base64-encoded), and a document type outside the live catalog before anything is sent.
* **Text PDFs only.** Scanned or image-only PDFs fail with `PDF_EXTRACTION_FAILED`. The generator reads text, not pictures.
* **Jobs take one to several minutes** and their records expire 24 hours after submission. `generate` and `parse` wait up to `--timeout` (420 seconds by default); use `--no-wait` plus `status --wait` to split the submission from the wait.
* **Read mode allows `document-types` and `status` only.** `generate` and `parse` create a job on the account and need `operate` or `full` mode.

## Related

* [file-definitions](/cli/commands/file-definitions.md) — save the generated rules as a file definition.
* [edi-profiles](/cli/commands/edi-profiles.md) — the interchange envelope for the trading partner the specification belongs to.
* [processors](/cli/commands/processors.md) — test parsing rules against a sample document without creating a resource.
* [edi-transactions](/cli/commands/edi-transactions.md) — the transaction log produced once documents are exchanged.