Skip to main content
SuperDoc SDKs let you open, read, and edit .docx files from Node.js or Python. They manage the CLI process for you and expose typed methods for every operation.
The SDKs are in alpha. The API surface matches the Document API and will evolve alongside it.

Installation

npm install @superdoc-dev/sdk
The CLI is bundled with the SDK — no separate install needed.

Quick start

The Node SDK supports both ESM and CommonJS:
// ESM
import { createSuperDocClient } from '@superdoc-dev/sdk';

// CommonJS
const { createSuperDocClient } = require('@superdoc-dev/sdk');
import { SuperDocClient } from '@superdoc-dev/sdk';

const client = new SuperDocClient({
  defaultChangeMode: 'tracked',
});

// Open a document
await client.doc.open({ doc: './contract.docx' });

// Find and replace text with query + mutation plan
const match = await client.doc.query.match({
  select: { type: 'text', pattern: 'ACME Corp' },
  require: 'first',
});

const ref = match.items?.[0]?.handle?.ref;
if (ref) {
  await client.doc.mutations.apply({
    expectedRevision: match.evaluatedRevision,
    atomic: true,
    steps: [
      {
        id: 'replace-acme',
        op: 'text.rewrite',
        where: { by: 'ref', ref },
        args: { replacement: { text: 'NewCo Inc.' } },
      },
    ],
  });
}

// Save and close
await client.doc.save();
await client.doc.close();
Set defaultChangeMode: 'tracked' (Node) or default_change_mode='tracked' (Python) to make mutations use tracked changes by default. If you pass changeMode on a specific call, that explicit value overrides the default. The Python SDK also exposes synchronous SuperDocClient with the same doc.* operations when you prefer non-async code paths.

User identity

By default the SDK attributes edits to a generic “CLI” user. Set user on the client to identify your automation in comments, tracked changes, and collaboration presence:
const client = new SuperDocClient({
  user: { name: 'Review Bot', email: 'bot@example.com' },
});
The user is injected into every doc.open call. If you pass userName or userEmail on a specific doc.open, those per-call values take precedence.

Collaboration sessions

Use this when your app already has a live collaboration room (Liveblocks, Hocuspocus, or SuperDoc Yjs).

Join an existing room

Pass collabUrl and collabDocumentId to doc.open:
import { SuperDocClient } from '@superdoc-dev/sdk';

const client = new SuperDocClient();
await client.connect();

await client.doc.open({
  collabUrl: 'ws://localhost:4000',
  collabDocumentId: 'my-doc-room',
});

await client.doc.insert({
  target: { type: 'end' },
  content: 'Added by the SDK',
});

Start an empty room from a local .docx

If the room is empty, pass doc together with collaboration params:
await client.doc.open({
  doc: './starting-template.docx',
  collabUrl: 'ws://localhost:4000',
  collabDocumentId: 'my-doc-room',
});
What happens when you pass doc:
Room stateResult
Room already has contentSDK joins the room. doc is ignored.
Room is empty and doc is providedSDK seeds the room from doc, then joins.
Room is empty and no doc is providedSDK starts a blank document.

Control empty-room behavior

ParameterTypeDefaultDescription
collabUrlstringWebSocket URL for your collaboration provider.
collabDocumentIdstringsession IDRoom/document ID on the provider.
docstringLocal .docx used only when the room is empty.
onMissingstringseedFromDocseedFromDoc, blank, or error.
bootstrapSettlingMsnumber1500Wait time (ms) before seeding to avoid race conditions.
If you only want to join rooms that already exist, use onMissing: 'error'.
await client.doc.open({
  collabUrl: 'ws://localhost:4000',
  collabDocumentId: 'my-doc-room',
  onMissing: 'error',
});

Check if the SDK seeded or joined

doc.open returns bootstrap details in collaboration mode:
const result = await client.doc.open({
  doc: './starting-template.docx',
  collabUrl: 'ws://localhost:4000',
  collabDocumentId: 'my-doc-room',
});

console.log(result.bootstrap);
// { roomState, bootstrapApplied, bootstrapSource }

Available operations

The SDKs expose all operations from the Document API plus lifecycle and session commands. The tables below are grouped by category.

Lifecycle

OperationCLI commandDescription
doc.openopenOpen a document and create a persistent editing session. Optionally override the document body with contentOverride + overrideType (markdown, html, or text).
doc.savesaveSave the current session to the original file or a new path.
doc.closecloseClose the active editing session and clean up resources.

Query

OperationCLI commandDescription
doc.findfindSearch the document for nodes matching type, text, or attribute criteria.
doc.getNodeget-nodeRetrieve a single node by target position.
doc.getNodeByIdget-node-by-idRetrieve a single node by its unique ID.
doc.getTextget-textExtract the plain-text content of the document.
doc.getMarkdownget-markdownExtract the document content as a Markdown string.
doc.getHtmlget-htmlExtract the document content as an HTML string.
doc.infoinfoReturn document metadata including revision, node count, and capabilities.
doc.query.matchquery matchDeterministic selector-based search with cardinality contracts for mutation targeting.
doc.mutations.previewmutations previewDry-run a mutation plan, returning resolved targets without applying changes.

Mutation

OperationCLI commandDescription
doc.insertinsertInsert content at a target position, or at the end of the document when target is omitted. Supports text (default), markdown, and html content types via the type field.
doc.replacereplaceReplace content at a target position with new text or inline content.
doc.deletedeleteDelete content at a target position.
doc.mutations.applymutations applyExecute a mutation plan atomically against the document.

Format

OperationCLI commandDescription
doc.format.applyformat applyApply inline run-property patch changes to the target range with explicit set/clear semantics.
doc.format.boldformat boldSet or clear the bold inline run property on the target text range.
doc.format.italicformat italicSet or clear the italic inline run property on the target text range.
doc.format.strikeformat strikeSet or clear the strike inline run property on the target text range.
doc.format.underlineformat underlineSet or clear the underline inline run property on the target text range.
doc.format.highlightformat highlightSet or clear the highlight inline run property on the target text range.
doc.format.colorformat colorSet or clear the color inline run property on the target text range.
doc.format.fontSizeformat font-sizeSet or clear the fontSize inline run property on the target text range.
doc.format.fontFamilyformat font-familySet or clear the fontFamily inline run property on the target text range.
doc.format.letterSpacingformat letter-spacingSet or clear the letterSpacing inline run property on the target text range.
doc.format.vertAlignformat vert-alignSet or clear the vertAlign inline run property on the target text range.
doc.format.positionformat positionSet or clear the position inline run property on the target text range.
doc.format.dstrikeformat dstrikeSet or clear the dstrike inline run property on the target text range.
doc.format.smallCapsformat small-capsSet or clear the smallCaps inline run property on the target text range.
doc.format.capsformat capsSet or clear the caps inline run property on the target text range.
doc.format.shadingformat shadingSet or clear the shading inline run property on the target text range.
doc.format.borderformat borderSet or clear the border inline run property on the target text range.
doc.format.outlineformat outlineSet or clear the outline inline run property on the target text range.
doc.format.shadowformat shadowSet or clear the shadow inline run property on the target text range.
doc.format.embossformat embossSet or clear the emboss inline run property on the target text range.
doc.format.imprintformat imprintSet or clear the imprint inline run property on the target text range.
doc.format.charScaleformat char-scaleSet or clear the charScale inline run property on the target text range.
doc.format.kerningformat kerningSet or clear the kerning inline run property on the target text range.
doc.format.vanishformat vanishSet or clear the vanish inline run property on the target text range.
doc.format.webHiddenformat web-hiddenSet or clear the webHidden inline run property on the target text range.
doc.format.specVanishformat spec-vanishSet or clear the specVanish inline run property on the target text range.
doc.format.rtlformat rtlSet or clear the rtl inline run property on the target text range.
doc.format.csformat csSet or clear the cs inline run property on the target text range.
doc.format.bCsformat b-csSet or clear the bCs inline run property on the target text range.
doc.format.iCsformat i-csSet or clear the iCs inline run property on the target text range.
doc.format.eastAsianLayoutformat east-asian-layoutSet or clear the eastAsianLayout inline run property on the target text range.
doc.format.emformat emSet or clear the em inline run property on the target text range.
doc.format.fitTextformat fit-textSet or clear the fitText inline run property on the target text range.
doc.format.snapToGridformat snap-to-gridSet or clear the snapToGrid inline run property on the target text range.
doc.format.langformat langSet or clear the lang inline run property on the target text range.
doc.format.oMathformat o-mathSet or clear the oMath inline run property on the target text range.
doc.format.rStyleformat r-styleSet or clear the rStyle inline run property on the target text range.
doc.format.rFontsformat r-fontsSet or clear the rFonts inline run property on the target text range.
doc.format.fontSizeCsformat font-size-csSet or clear the fontSizeCs inline run property on the target text range.
doc.format.ligaturesformat ligaturesSet or clear the ligatures inline run property on the target text range.
doc.format.numFormformat num-formSet or clear the numForm inline run property on the target text range.
doc.format.numSpacingformat num-spacingSet or clear the numSpacing inline run property on the target text range.
doc.format.stylisticSetsformat stylistic-setsSet or clear the stylisticSets inline run property on the target text range.
doc.format.contextualAlternatesformat contextual-alternatesSet or clear the contextualAlternates inline run property on the target text range.

Format / Paragraph

OperationCLI commandDescription
doc.format.paragraph.resetDirectFormattingformat paragraph reset-direct-formattingStrip all direct paragraph formatting while preserving style reference, numbering, and section metadata.
doc.format.paragraph.setAlignmentformat paragraph set-alignmentSet paragraph alignment (justification) on a paragraph-like block.
doc.format.paragraph.clearAlignmentformat paragraph clear-alignmentRemove direct paragraph alignment, reverting to style-defined or default alignment.
doc.format.paragraph.setIndentationformat paragraph set-indentationSet paragraph indentation properties (left, right, firstLine, hanging) in twips.
doc.format.paragraph.clearIndentationformat paragraph clear-indentationRemove all direct paragraph indentation.
doc.format.paragraph.setSpacingformat paragraph set-spacingSet paragraph spacing properties (before, after, line, lineRule) in twips.
doc.format.paragraph.clearSpacingformat paragraph clear-spacingRemove all direct paragraph spacing.
doc.format.paragraph.setKeepOptionsformat paragraph set-keep-optionsSet keep-with-next, keep-lines-together, and widow/orphan control flags.
doc.format.paragraph.setOutlineLevelformat paragraph set-outline-levelSet the paragraph outline level (0–9) or null to clear.
doc.format.paragraph.setFlowOptionsformat paragraph set-flow-optionsSet contextual spacing, page-break-before, and suppress-auto-hyphens flags.
doc.format.paragraph.setTabStopformat paragraph set-tab-stopAdd or replace a tab stop at a given position.
doc.format.paragraph.clearTabStopformat paragraph clear-tab-stopRemove a tab stop at a given position.
doc.format.paragraph.clearAllTabStopsformat paragraph clear-all-tab-stopsRemove all tab stops from a paragraph.
doc.format.paragraph.setBorderformat paragraph set-borderSet border properties for a specific side of a paragraph.
doc.format.paragraph.clearBorderformat paragraph clear-borderRemove border for a specific side or all sides of a paragraph.
doc.format.paragraph.setShadingformat paragraph set-shadingSet paragraph shading (background fill, pattern color, pattern type).
doc.format.paragraph.clearShadingformat paragraph clear-shadingRemove all paragraph shading.

Styles

OperationCLI commandDescription
doc.styles.applystyles applyApply document-level default style changes to the stylesheet (word/styles.xml). Targets docDefaults run and paragraph channels with set-style patch semantics.

Styles / Paragraph

OperationCLI commandDescription
doc.styles.paragraph.setStylestyles paragraph set-styleSet the paragraph style reference (w:pStyle) on a paragraph-like block.
doc.styles.paragraph.clearStylestyles paragraph clear-styleRemove the paragraph style reference from a paragraph-like block.

Create

OperationCLI commandDescription
doc.create.paragraphcreate paragraphCreate a new paragraph at the target position.
doc.create.headingcreate headingCreate a new heading at the target position.
doc.create.sectionBreakcreate section-breakCreate a section break at the target location with optional initial section properties.
doc.create.tablecreate tableCreate a new table at the target position.
doc.create.tableOfContentscreate table-of-contentsInsert a new table of contents at the target position.
doc.create.imagecreate imageInsert a new image at the target position.

Sections

OperationCLI commandDescription
doc.sections.listsections listList sections in deterministic order with section-target handles.
doc.sections.getsections getRetrieve full section information by section address.
doc.sections.setBreakTypesections set-break-typeSet the section break type.
doc.sections.setPageMarginssections set-page-marginsSet page-edge margins for a section.
doc.sections.setHeaderFooterMarginssections set-header-footer-marginsSet header/footer margin distances for a section.
doc.sections.setPageSetupsections set-page-setupSet page size/orientation properties for a section.
doc.sections.setColumnssections set-columnsSet column configuration for a section.
doc.sections.setLineNumberingsections set-line-numberingEnable or configure line numbering for a section.
doc.sections.setPageNumberingsections set-page-numberingSet page numbering format/start for a section.
doc.sections.setTitlePagesections set-title-pageEnable or disable title-page behavior for a section.
doc.sections.setOddEvenHeadersFooterssections set-odd-even-headers-footersEnable or disable odd/even header-footer mode in document settings.
doc.sections.setVerticalAlignsections set-vertical-alignSet vertical page alignment for a section.
doc.sections.setSectionDirectionsections set-section-directionSet section text flow direction (LTR/RTL).
doc.sections.setHeaderFooterRefsections set-header-footer-refSet or replace a section header/footer reference for a variant.
doc.sections.clearHeaderFooterRefsections clear-header-footer-refClear a section header/footer reference for a specific variant.
doc.sections.setLinkToPrevioussections set-link-to-previousSet or clear link-to-previous behavior for a header/footer variant.
doc.sections.setPageBorderssections set-page-bordersSet page border configuration for a section.
doc.sections.clearPageBorderssections clear-page-bordersClear page border configuration for a section.

Blocks

OperationCLI commandDescription
doc.blocks.deleteblocks deleteDelete an entire block node (paragraph, heading, list item, table, image, or sdt) deterministically.

Lists

OperationCLI commandDescription
doc.lists.listlists listList all list nodes in the document, optionally filtered by scope.
doc.lists.getlists getRetrieve a specific list node by target.
doc.lists.insertlists insertInsert a new list at the target position.
doc.lists.createlists createCreate a new list from one or more paragraphs, or convert existing paragraphs into a new list.
doc.lists.attachlists attachConvert non-list paragraphs to list items under an existing list sequence.
doc.lists.detachlists detachRemove numbering properties from list items, converting them to plain paragraphs.
doc.lists.indentlists indentIncrease the indentation level of a list item.
doc.lists.outdentlists outdentDecrease the indentation level of a list item.
doc.lists.joinlists joinMerge two adjacent list sequences into one.
doc.lists.canJoinlists can-joinCheck whether two adjacent list sequences can be joined.
doc.lists.separatelists separateSplit a list sequence at the target item, creating a new sequence from that point forward.
doc.lists.setLevellists set-levelSet the absolute nesting level (0..8) of a list item.
doc.lists.setValuelists set-valueSet an explicit numbering value at the target item. Mid-sequence targets are atomically separated first.
doc.lists.continuePreviouslists continue-previousContinue numbering from the nearest compatible previous list sequence.
doc.lists.canContinuePreviouslists can-continue-previousCheck whether the target sequence can continue numbering from a previous compatible sequence.
doc.lists.setLevelRestartlists set-level-restartSet the restart behavior for a specific list level.
doc.lists.convertToTextlists convert-to-textConvert list items to plain paragraphs, optionally prepending the rendered marker text.

Tables

OperationCLI commandDescription
doc.tables.convertFromTexttables convert-from-textConvert a text range into a table.
doc.tables.deletetables deleteDelete the target table from the document.
doc.tables.clearContentstables clear-contentsClear the contents of the target table or cell range.
doc.tables.movetables moveMove a table to a new position in the document.
doc.tables.splittables splitSplit a table into two tables at the target row.
doc.tables.convertToTexttables convert-to-textConvert a table back to plain text.
doc.tables.setLayouttables set-layoutSet the layout mode of the target table.
doc.tables.insertRowtables insert-rowInsert a new row into the target table.
doc.tables.deleteRowtables delete-rowDelete a row from the target table.
doc.tables.setRowHeighttables set-row-heightSet the height of a table row.
doc.tables.distributeRowstables distribute-rowsDistribute row heights evenly across the target table.
doc.tables.setRowOptionstables set-row-optionsSet options on a table row such as header repeat or page break.
doc.tables.insertColumntables insert-columnInsert a new column into the target table.
doc.tables.deleteColumntables delete-columnDelete a column from the target table.
doc.tables.setColumnWidthtables set-column-widthSet the width of a table column.
doc.tables.distributeColumnstables distribute-columnsDistribute column widths evenly across the target table.
doc.tables.insertCelltables insert-cellInsert a new cell into a table row.
doc.tables.deleteCelltables delete-cellDelete a cell from a table row.
doc.tables.mergeCellstables merge-cellsMerge a range of table cells into one.
doc.tables.unmergeCellstables unmerge-cellsUnmerge a previously merged table cell.
doc.tables.splitCelltables split-cellSplit a table cell into multiple cells.
doc.tables.setCellPropertiestables set-cell-propertiesSet properties on a table cell such as vertical alignment or text direction.
doc.tables.sorttables sortSort table rows by a column value.
doc.tables.setAltTexttables set-alt-textSet the alternative text description for a table.
doc.tables.setStyletables set-styleApply a named table style to the target table.
doc.tables.clearStyletables clear-styleRemove the applied table style, reverting to defaults.
doc.tables.setStyleOptiontables set-style-optionToggle a conditional style option such as banded rows or first column.
doc.tables.setBordertables set-borderSet border properties on a table or cell range.
doc.tables.clearBordertables clear-borderRemove border formatting from a table or cell range.
doc.tables.applyBorderPresettables apply-border-presetApply a border preset (e.g. all borders, outside only) to a table.
doc.tables.setShadingtables set-shadingSet the background shading color on a table or cell range.
doc.tables.clearShadingtables clear-shadingRemove shading from a table or cell range.
doc.tables.setTablePaddingtables set-table-paddingSet default cell padding for the entire table.
doc.tables.setCellPaddingtables set-cell-paddingSet padding on a specific table cell or cell range.
doc.tables.setCellSpacingtables set-cell-spacingSet the cell spacing for the target table.
doc.tables.clearCellSpacingtables clear-cell-spacingRemove custom cell spacing from the target table.
doc.tables.gettables getRetrieve table structure and dimensions by locator.
doc.tables.getCellstables get-cellsRetrieve cell information for a table, optionally filtered by row or column.
doc.tables.getPropertiestables get-propertiesRetrieve layout and style properties of a table.
doc.tables.getStylestables get-stylesList all table styles and the document-level default table style setting.
doc.tables.setDefaultStyletables set-default-styleSet the document-level default table style (w:defaultTableStyle in settings.xml).
doc.tables.clearDefaultStyletables clear-default-styleRemove the document-level default table style setting.

Table of contents

OperationCLI commandDescription
doc.toc.listtoc listList all tables of contents in the document.
doc.toc.gettoc getRetrieve details of a specific table of contents.
doc.toc.configuretoc configureUpdate the configuration switches of a table of contents.
doc.toc.updatetoc updateRebuild or refresh the materialized content of a table of contents.
doc.toc.removetoc removeRemove a table of contents from the document.
doc.toc.markEntrytoc mark-entryInsert a TC (table of contents entry) field at the target paragraph.
doc.toc.unmarkEntrytoc unmark-entryRemove a TC (table of contents entry) field from the document.
doc.toc.listEntriestoc list-entriesList all TC (table of contents entry) fields in the document body.
doc.toc.getEntrytoc get-entryRetrieve details of a specific TC (table of contents entry) field.
doc.toc.editEntrytoc edit-entryUpdate the properties of a TC (table of contents entry) field.

Comments

OperationCLI commandDescription
doc.comments.createcomments createCreate a new comment thread (or reply when parentCommentId is given).
doc.comments.patchcomments patchPatch fields on an existing comment (text, target, status, or isInternal).
doc.comments.deletecomments deleteRemove a comment or reply by ID.
doc.comments.getcomments getRetrieve a single comment thread by ID.
doc.comments.listcomments listList all comment threads in the document.

Track changes

OperationCLI commandDescription
doc.trackChanges.listtrack-changes listList all tracked changes in the document.
doc.trackChanges.gettrack-changes getRetrieve a single tracked change by ID.
doc.trackChanges.decidetrack-changes decideAccept or reject a tracked change (by ID or scope: all).

Capabilities

OperationCLI commandDescription
doc.capabilities.getcapabilitiesQuery runtime capabilities supported by the current document engine.

History

OperationCLI commandDescription
doc.history.gethistory getQuery the current undo/redo history state of the active editor.
doc.history.undohistory undoUndo the most recent history-safe mutation in the active editor.
doc.history.redohistory redoRedo the most recently undone action in the active editor.

Session

OperationCLI commandDescription
doc.session.listsession listList all active editing sessions.
doc.session.savesession savePersist the current session state.
doc.session.closesession closeClose a specific editing session by ID.
doc.session.setDefaultsession set-defaultSet the default session for subsequent commands.

Introspection

OperationCLI commandDescription
doc.statusstatusShow the current session status and document metadata.
doc.describedescribeList all available CLI operations and contract metadata.
doc.describeCommanddescribe commandShow detailed metadata for a single CLI operation.

Images

OperationCLI commandDescription
doc.images.listimages listList all images in the document.
doc.images.getimages getGet details for a specific image by its stable ID.
doc.images.deleteimages deleteDelete an image from the document.
doc.images.moveimages moveMove an image to a new location in the document.
doc.images.convertToInlineimages convert-to-inlineConvert a floating image to inline placement.
doc.images.convertToFloatingimages convert-to-floatingConvert an inline image to floating placement.
doc.images.setSizeimages set-sizeSet explicit width/height for an image.
doc.images.setWrapTypeimages set-wrap-typeSet the text wrapping type for a floating image.
doc.images.setWrapSideimages set-wrap-sideSet which side(s) text wraps around a floating image.
doc.images.setWrapDistancesimages set-wrap-distancesSet the text-wrap distance margins for a floating image.
doc.images.setPositionimages set-positionSet the anchor position for a floating image.
doc.images.setAnchorOptionsimages set-anchor-optionsSet anchor behavior options for a floating image.
doc.images.setZOrderimages set-z-orderSet the z-order (relativeHeight) for a floating image.
  • Document API — the in-browser API that defines the operation set
  • CLI — use the same operations from the terminal
  • Collaboration guides — set up Liveblocks, Hocuspocus, or SuperDoc Yjs