> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.