> 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/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/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/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/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/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/file-definitions#get-v1-filedefinitions-_id) followed by [`PUT /v1/filedefinitions/{_id}`](https://developer.celigo.com/api/api-reference/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/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.


---

# 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/file-definitions.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.