> 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-definitions.md).

# 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/b2b-manager/file-definitions)

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

Supports all [global flags](/cli/getting-started/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 a JSON body (`--file <path>` or stdin).              |
| `update`                              | Full replace from a JSON body (`--file <path>` or stdin); destructive `PUT`.       |
| `set`                                 | Patch one or more fields via `GET` → modify → `PUT`. Supports `key=file://<path>`. |
| `delete`                              | Delete a file definition by ID.                                                    |
| `dependencies <id>` (alias `used-by`) | List resources that depend on this file definition.                                |
| `audit <id>`                          | Show the file definition's audit log (change history).                             |

***

## `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/getting-started/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/b2b-manager/file-definitions#get-v1-filedefinitions)

***

## `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/getting-started/global-flags.md).

**Example**

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

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

***

## `celigo file-definitions create`

Create a new file definition from a JSON body. Read the body from a file with `-f, --file`, or pipe it 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 --file <path>
celigo file-definitions create < body.json     # or pipe on stdin
```

**Arguments**

None.

**Flags**

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

Blocked in `read` mode.

**Example**

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

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

***

## `celigo file-definitions update`

Replace an existing file definition with a JSON body (`--file <path>` or stdin). PUT is a full replace — omitted fields are cleared.

> ⚠️ **`PUT` fully replaces the file definition.** Any omitted field is cleared, including the nested parsing rule tree. Prefer `set`, or `get | jq | update`, to preserve the rest of the document.

**Signature**

```bash
celigo file-definitions update <id> --file <path>
celigo file-definitions update <id> < body.json     # or pipe on stdin
```

**Arguments**

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

**Flags**

| Flag                | Type    | Default | Description                                                                                                  |
| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `-f, --file <path>` | string  | —       | Read the JSON body from a file instead of stdin (`--file -` also means stdin). Added in celigo-cli 2026.6.1. |
| `--force`           | boolean | `false` | Submit even if the body contains masked credential values (`***`) copied from a `GET`.                       |

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/b2b-manager/file-definitions#put-v1-filedefinitions-_id)

***

## `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. Use `key=file://<path>` to load a value from a file (added in celigo-cli 2026.6.1). |

**Flags**

None beyond the [global flags](/cli/getting-started/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/b2b-manager/file-definitions#get-v1-filedefinitions-_id) followed by [`PUT /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/b2b-manager/file-definitions#put-v1-filedefinitions-_id).

***

## `celigo file-definitions delete`

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

> ⚠️ **Deleting a file definition is destructive.** Exports and imports that reference it by ID will break. Run `dependencies` first to confirm nothing references it.

**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/b2b-manager/file-definitions#delete-v1-filedefinitions-_id)

***

## `celigo file-definitions dependencies`

List resources that depend on this file definition (alias: `used-by`). Use it to check whether a file definition is safe to delete — an empty result means nothing references it.

**Signature**

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

**Arguments**

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

**Example**

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

**Corresponds to**: `GET /v1/filedefinitions/{_id}/dependencies`

***

## `celigo file-definitions audit`

Show the audit log (change history) for one file definition.

**Signature**

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

**Arguments**

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

**Example**

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

**Corresponds to**: `GET /v1/filedefinitions/{_id}/audit`

***

## 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/commands/edi-profiles.md) — trading-partner-level EDI configuration that pairs with X12/EDIFACT file definitions.
* [exports](/cli/commands/exports.md) — file-based exports (FTP, S3, local files) reference a file definition to parse inbound data.
* [imports](/cli/commands/imports.md) — file-based imports reference a file definition to generate outbound files.