Skip to main content
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: 
# Open a document
superdoc open contract.docx

# Search for text
superdoc find --pattern "ACME Corp"

# Replace it
superdoc replace --target-json '{"kind":"selection","start":{"kind":"text","blockId":"...","offset":0},"end":{"kind":"text","blockId":"...","offset":9}}' --text "NewCo Inc."

# Save and close
superdoc save
superdoc close
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.

​
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 "[email protected]"

​
Commands

​
Lifecycle

CommandDescription
superdoc open <doc>Open a document and create an editing session. Supports --user-name and --user-email to set the editing identity. In collaboration mode, also supports --on-missing and --bootstrap-settling-ms.
superdoc saveSave the current session to disk
superdoc closeClose 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 commandOperationDescription
superdoc findfindSearch by text, node type, or structured query
superdoc infoinfoGet document structure and metadata
superdoc get-nodegetNodeGet a node by address
superdoc get-node-by-idgetNodeByIdGet a node by ID
superdoc insertinsertInsert text at a position
superdoc replacereplaceReplace content at a selection
superdoc deletedeleteDelete content at a selection
superdoc format boldformat.boldToggle bold on a selection
superdoc format italicformat.italicToggle italic on a selection
superdoc format underlineformat.underlineToggle underline on a selection
superdoc format strikethroughformat.strikethroughToggle strikethrough on a selection
superdoc ranges resolveranges.resolveResolve a selection from explicit anchors
superdoc create paragraphcreate.paragraphInsert a new paragraph
superdoc comments createcomments.createCreate a comment thread
superdoc comments listcomments.listList all comments
superdoc track-changes listtrackChanges.listList tracked changes
superdoc track-changes decidetrackChanges.decideAccept or reject a tracked change
Run superdoc --help for the full list, or superdoc describe for machine-readable metadata.

​
Session management

CommandDescription
superdoc session listList 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

CommandDescription
superdoc statusShow current session status and document metadata
superdoc describeList 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"}}}'
  • SDKs — typed Node.js and Python wrappers over the CLI
  • Document API — the in-browser API that defines the operation set