> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-caio-pizzol-docs-ai-core-preset.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Edit documents from the terminal with the SuperDoc CLI

The SuperDoc CLI lets you open, query, and edit `.docx` files from any shell. It exposes the same operations as the [Document API](/document-api/overview) through a stdio-based process.

## Installation

```bash theme={null}
npm install -g @superdoc-dev/cli
```

Or run without installing:

```bash theme={null}
npx @superdoc-dev/cli open my-doc.docx
```

## Workflow

The CLI uses persistent sessions. Open a document, run operations, then save and close.

### Edit an existing document

```bash theme={null}
superdoc open contract.docx

superdoc query match --select-json '{"type":"text","pattern":"ACME Corp"}' --require exactlyOne
superdoc replace --target-json '{"kind":"selection","start":{"kind":"text","blockId":"...","offset":0},"end":{"kind":"text","blockId":"...","offset":9}}' --text "NewCo Inc."

superdoc save
superdoc close
```

Use `query match` for edits against existing content because it returns mutation-ready targets with explicit cardinality.

### Generate a synthetic document body

Use `open --content-override` when you want to seed a document body from Markdown, HTML, or plain text:

```bash theme={null}
superdoc open --content-override "# Probe Title\n\nALPHA01" --override-type markdown
superdoc save --out probe.docx
superdoc close
```

```bash theme={null}
superdoc open template.docx \
  --content-override '<p>ALPHA01 <strong>BRAVO02</strong><br/>CHARLIE03</p>' \
  --override-type html
superdoc save --out probe.docx
superdoc close
```

For generation, start with `content-override` or `insert`. Do not begin with `query match` unless you are modifying pre-existing content.

### Seed text, then reuse the insert receipt target

For deterministic probe docs, insert the text first and format the returned range directly:

```bash theme={null}
superdoc open
superdoc insert --value "ALPHA01 BRAVO02 CHARLIE03"
superdoc format apply --block-id <from-insert-receipt> --start 8 --end 15 --inline-json '{"fontSize":16,"fontFamily":"Times New Roman"}'
superdoc format apply --block-id <from-insert-receipt> --start 16 --end 25 --inline-json '{"fontSize":10,"fontFamily":"Arial"}'
superdoc save --out probe.docx
superdoc close
```

The insert receipt exposes the resolved insertion point under `receipt.resolution.target`.

For `replace`, `delete`, and `format.*`, prefer canonical `SelectionTarget` JSON or a mutation-ready `ref`. The CLI still accepts legacy single-block text ranges such as `{"kind":"text","blockId":"...","range":{"start":0,"end":9}}` and upgrades them automatically for compatibility, but new scripts should use the canonical selection form.

## Inline tabs and line breaks

`insert tab` and `insert line-break` create real inline Word nodes in the current paragraph:

```bash theme={null}
superdoc insert tab --block-id p1 --offset 12
superdoc insert line-break --block-id p1 --offset 12
```

This is different from paragraph tab stops. Tab stops define layout positions on the paragraph. Tab nodes and line-break nodes are inline document content that export as `w:tab` and `w:br`.

## Tracked mode for mutations

Use `--tracked` on mutating commands to apply edits as tracked changes instead of direct edits.

```bash theme={null}
# Replace text as a tracked change
superdoc replace \
  --target-json '{"kind":"selection","start":{"kind":"text","blockId":"...","offset":0},"end":{"kind":"text","blockId":"...","offset":9}}' \
  --text "NewCo Inc." \
  --tracked

# Insert text as a tracked change
superdoc insert --value "Added clause" --tracked
```

`--tracked` is shorthand for `--change-mode tracked`:

```bash theme={null}
superdoc replace \
  --target-json '{"kind":"selection","start":{"kind":"text","blockId":"...","offset":0},"end":{"kind":"text","blockId":"...","offset":9}}' \
  --text "NewCo Inc." \
  --change-mode tracked
```

For commands that do not support tracked mode, the CLI returns `TRACK_CHANGE_COMMAND_UNAVAILABLE`.

## User identity

By default, the CLI attributes edits to a generic "CLI" user. Pass `--user-name` and `--user-email` on `open` to identify your automation in comments, tracked changes, and collaboration presence:

```bash theme={null}
superdoc open contract.docx --user-name "Review Bot" --user-email "bot@example.com"
```

## Commands

### Lifecycle

| Command               | Description                                                                                                                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `superdoc open <doc>` | Open a document and create an editing session. Supports `--content-override` + `--override-type` for body seeding, plus `--user-name` and `--user-email` for editing identity. In collaboration mode, also supports `--on-missing` and `--bootstrap-settling-ms`. |
| `superdoc save`       | Save the current session to disk                                                                                                                                                                                                                                  |
| `superdoc close`      | Close the active session and clean up resources                                                                                                                                                                                                                   |

### Document operations

The CLI exposes all [Document API operations](/document-api/overview) as commands. The command name matches the operation's member path, converted to kebab-case:

| CLI command                     | Operation              | Description                                                          |
| ------------------------------- | ---------------------- | -------------------------------------------------------------------- |
| `superdoc find`                 | `find`                 | Search by text, node type, or structured query                       |
| `superdoc info`                 | `info`                 | Get document structure and metadata                                  |
| `superdoc get-node`             | `getNode`              | Get a node by address                                                |
| `superdoc get-node-by-id`       | `getNodeById`          | Get a node by ID                                                     |
| `superdoc insert`               | `insert`               | Insert text at a position                                            |
| `superdoc insert tab`           | CLI-only               | Insert a real inline Word tab node at a collapsed text target        |
| `superdoc insert line-break`    | CLI-only               | Insert a real inline Word line-break node at a collapsed text target |
| `superdoc replace`              | `replace`              | Replace content at a selection                                       |
| `superdoc delete`               | `delete`               | Delete content at a selection                                        |
| `superdoc format bold`          | `format.bold`          | Toggle bold on a selection                                           |
| `superdoc format italic`        | `format.italic`        | Toggle italic on a selection                                         |
| `superdoc format underline`     | `format.underline`     | Toggle underline on a selection                                      |
| `superdoc format strikethrough` | `format.strikethrough` | Toggle strikethrough on a selection                                  |
| `superdoc ranges resolve`       | `ranges.resolve`       | Resolve a selection from explicit anchors                            |
| `superdoc create paragraph`     | `create.paragraph`     | Insert a new paragraph                                               |
| `superdoc comments create`      | `comments.create`      | Create a comment thread                                              |
| `superdoc comments list`        | `comments.list`        | List all comments                                                    |
| `superdoc track-changes list`   | `trackChanges.list`    | List tracked changes                                                 |
| `superdoc track-changes decide` | `trackChanges.decide`  | Accept or reject a tracked change                                    |

Run `superdoc --help` for the full list, or `superdoc describe` for machine-readable metadata.

### Session management

| Command                             | Description                                     |
| ----------------------------------- | ----------------------------------------------- |
| `superdoc session list`             | List all active sessions                        |
| `superdoc session save <id>`        | Save a specific session                         |
| `superdoc session close <id>`       | Close a specific session                        |
| `superdoc session set-default <id>` | Set the default session for subsequent commands |

### Introspection

| Command                           | Description                                         |
| --------------------------------- | --------------------------------------------------- |
| `superdoc status`                 | Show current session status and document metadata   |
| `superdoc describe`               | List all available operations and contract metadata |
| `superdoc describe command <cmd>` | Show detailed metadata for a single operation       |

## JSON I/O

All commands accept `--input-json` or `--input-file` for structured input and return JSON output. Use `superdoc call <operationId>` for raw operation invocation:

```bash theme={null}
superdoc call doc.find --input-json '{"doc":"./contract.docx","query":{"select":{"type":"text","pattern":"test"}}}'
```

In `--output json` mode, command results are returned as a JSON envelope. Use `--quiet` to suppress non-essential warnings in pretty mode.

## Related

* [SDKs](/document-engine/sdks): typed Node.js and Python wrappers over the CLI
* [Document API](/document-api/overview): the in-browser API that defines the operation set