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 through a stdio-based process.

Installation

npm install -g @superdoc-dev/cli

Or run without installing:

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

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:

superdoc open --content-override "# Probe Title\n\nALPHA01" --override-type markdown
superdoc save --out probe.docx
superdoc close

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:

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:

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.

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

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:

superdoc open contract.docx --user-name "Review Bot" --user-email "[e-mail]"

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 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:

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: typed Node.js and Python wrappers over the CLI
• Document API: the in-browser API that defines the operation set