# file-definitions

Parsing and generation rules for structured file formats — fixed-width, delimited (CSV/TSV), X12, and EDIFACT. Referenced by exports and imports that process file-based payloads.

**REST API**: [File Definitions](https://developer.celigo.com/api/api-reference/file-definitions)

```
celigo file-definitions <subcommand> [args] [flags]
```

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

***

## Subcommands

| Subcommand | Purpose                                              |
| ---------- | ---------------------------------------------------- |
| `list`     | List every file definition in the account.           |
| `get`      | Fetch a single file definition by ID.                |
| `create`   | Create a file definition from JSON on stdin.         |
| `update`   | Replace a file definition with JSON on stdin.        |
| `set`      | Patch one or more fields via `GET` → modify → `PUT`. |
| `delete`   | Delete a file definition by ID.                      |

***

## `celigo file-definitions list`

List all file definitions configured on the account.

**Signature**

```bash
celigo file-definitions list
```

**Arguments**

None.

**Flags**

None beyond the [global flags](/cli/setup/global-flags.md) (`--format`, `--jq`, `--profile`, `--verbose`).

**Example**

```bash
celigo file-definitions list --format table
```

Default table columns: `_id`, `name`, `lastModified`.

**Corresponds to**: [`GET /v1/filedefinitions`](https://developer.celigo.com/api/api-reference/file-definitions#list-file-definitions)

***

## `celigo file-definitions get`

Fetch one file definition, including its full parsing rule tree.

**Signature**

```bash
celigo file-definitions get <id>
```

**Arguments**

| Argument | Type   | Required | Description                               |
| -------- | ------ | -------- | ----------------------------------------- |
| `<id>`   | string | Yes      | File definition `_id` (24-character hex). |

**Flags**

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

**Example**

```bash
celigo file-definitions get 63a1f2c9d4b1e70011a35f2c
```

**Corresponds to**: [`GET /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/file-definitions#get-a-file-definition)

***

## `celigo file-definitions create`

Create a new file definition from a JSON document piped on stdin. See the create request schema for the full body shape (format, rule tree, delimiters, and EDI `globalId`).

**Signature**

```bash
celigo file-definitions create < body.json
```

**Arguments**

None. The full request body is piped via stdin.

**Flags**

None beyond the [global flags](/cli/setup/global-flags.md). Blocked in `read` mode.

**Example**

```bash
celigo file-definitions create < invoice-fixed-width.json
```

**Corresponds to**: [`POST /v1/filedefinitions`](https://developer.celigo.com/api/api-reference/file-definitions#create-a-file-definition)

***

## `celigo file-definitions update`

Replace an existing file definition with the JSON document on stdin. PUT is a full replace — omitted fields are cleared.

**Signature**

```bash
celigo file-definitions update <id> < body.json
```

**Arguments**

| Argument | Type   | Required | Description                       |
| -------- | ------ | -------- | --------------------------------- |
| `<id>`   | string | Yes      | File definition `_id` to replace. |

**Flags**

None beyond the [global flags](/cli/setup/global-flags.md). Blocked in `read` mode.

**Example**

```bash
celigo file-definitions get 63a1f2c9d4b1e70011a35f2c --format json \
  | jq '.name = "Invoice v2"' \
  | celigo file-definitions update 63a1f2c9d4b1e70011a35f2c
```

**Corresponds to**: [`PUT /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/file-definitions#update-a-file-definition)

***

## `celigo file-definitions set`

Patch one or more fields on a file definition without re-sending the full document. The CLI does `GET` → apply assignments → `PUT`, which preserves unmodified fields (including the nested rule tree).

**Signature**

```bash
celigo file-definitions set <id> <key=value> [<key=value>...]
```

**Arguments**

| Argument      | Type   | Required | Description                                                                                                                                                                                   |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<id>`        | string | Yes      | File definition `_id` to modify.                                                                                                                                                              |
| `<key=value>` | string | Yes (≥1) | One or more assignments. Values are auto-parsed as JSON — `null` removes the field. Dot notation (`rules.delimiter=","`) and array indexing (`rules.elements[0].name=orderId`) are supported. |

**Flags**

None beyond the [global flags](/cli/setup/global-flags.md). Blocked in `read` mode.

**Examples**

```bash
celigo file-definitions set 63a1f2c9d4b1e70011a35f2c name="Invoice v2"
celigo file-definitions set 63a1f2c9d4b1e70011a35f2c description=null
celigo file-definitions set 63a1f2c9d4b1e70011a35f2c rules.elements[0].name=orderId
```

**Corresponds to**: [`GET /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/file-definitions#get-a-file-definition) followed by [`PUT /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/file-definitions#update-a-file-definition).

***

## `celigo file-definitions delete`

Delete a file definition by ID. Prompts for confirmation unless `-y/--yes` is supplied.

**Signature**

```bash
celigo file-definitions delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description                      |
| -------- | ------ | -------- | -------------------------------- |
| `<id>`   | string | Yes      | File definition `_id` to delete. |

**Flags**

| Flag        | Type    | Default | Description                               |
| ----------- | ------- | ------- | ----------------------------------------- |
| `-y, --yes` | boolean | `false` | Skip the interactive confirmation prompt. |

**Example**

```bash
celigo file-definitions delete 63a1f2c9d4b1e70011a35f2c --yes
```

**Corresponds to**: [`DELETE /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/file-definitions#delete-a-file-definition)

***

## Gotchas

* **EDI formats need a `globalId`.** `delimited/x12` and `delimited/edifact` definitions must reference a known standard document definition via `globalId`. Accounts without an EDI license cannot create these formats via the API — use the UI to generate them from a standard.
* **PUT is a full replace.** The parsing rule tree is deeply nested; a bare `update` that omits `rules` will erase it. Prefer `set` for small edits, or `get | jq | update` to preserve the rest of the document.
* **File definitions are referenced, not owned.** Exports and imports link to a file definition by ID (`file.fileDefinition._id`). Deleting a file definition that is still referenced will break those flows — list the references first before removing.
* **Name conflicts are not enforced.** Two file definitions with identical `name` values can coexist; always key off `_id` when linking from an export or import.

## Related

* [edi-profiles](/cli/b2b-edi/edi-profiles.md) — trading-partner-level EDI configuration that pairs with X12/EDIFACT file definitions.
* [exports](/cli/build/exports.md) — file-based exports (FTP, S3, local files) reference a file definition to parse inbound data.
* [imports](/cli/build/imports.md) — file-based imports reference a file definition to generate outbound files.


---

# Agent Instructions: 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:

```
GET https://developer.celigo.com/cli/b2b-edi/file-definitions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.