@superdoc-dev/superdoc-cli

LLM-first CLI for deterministic DOCX operations through SuperDoc's Document API.

Install

npm install -g @superdoc-dev/superdoc-cli

The package automatically installs a native binary for your platform via optionalDependencies. Supported platforms:

| Platform | Package | |----------|---------| | macOS (Apple Silicon) | @superdoc-dev/cli-darwin-arm64 | | macOS (Intel) | @superdoc-dev/cli-darwin-x64 | | Linux (x64) | @superdoc-dev/cli-linux-x64 | | Linux (ARM64) | @superdoc-dev/cli-linux-arm64 | | Windows (x64) | @superdoc-dev/cli-windows-x64 |

Usage

superdoc <command> [options]

Normative Policy

• Canonical contract/version metadata comes from @superdoc/document-api (CONTRACT_VERSION, operation metadata, and schemas).
• This README is usage guidance for CLI consumers.
• If guidance here conflicts with superdoc describe/describe command output or document-api contract exports, those are authoritative.

Host mode (stdio JSON-RPC)

superdoc host --stdio

• Starts a persistent JSON-RPC 2.0 host over newline-delimited stdio frames.
• Intended for SDK/runtime integrations that need long-lived command execution in a single process.
• Supported methods:
  • host.ping
  • host.capabilities
  • host.describe
  • host.describe.command (requires params.operationId)
  • host.shutdown
  • cli.invoke (executes canonical CLI command semantics)

API introspection commands

superdoc describe
superdoc describe command doc.find
superdoc status

• describe returns contract + protocol metadata and the operation catalog.
• describe command <operationId> returns one operation definition (inputs, response schema, errors, examples).
• status shows current session status and document metadata.

Stateful session commands

superdoc open ./contract.docx
superdoc status
superdoc find --type text --pattern "termination"
superdoc replace --target-json '{...}' --text "Updated clause"
superdoc save --in-place
superdoc close

• open creates a new session id automatically unless --session <id> is provided.
• If <doc> is omitted, commands run against the active default session.
• Explicit <doc> (or --doc) always runs in stateless mode and does not use session state.

Session management

superdoc session list
superdoc session save <sessionId> [--in-place] [--out <path>] [--force]
superdoc session set-default <sessionId>
superdoc session use <sessionId>
superdoc session close <sessionId> [--discard]

Read / locate commands

superdoc info [<doc>]
superdoc find [<doc>] --type text --pattern "termination"
superdoc find [<doc>] --type run
superdoc get-node [<doc>] --address-json '{"kind":"block","nodeType":"paragraph","nodeId":"p1"}'
superdoc get-node-by-id [<doc>] --id p1 --node-type paragraph

• Flat find flags are convenience syntax and are normalized into the canonical query object used by editor.doc.find.
• Use --query-json / --query-file for complex or programmatic queries.
• For text queries, use result.context[*].textRanges[*] as targets for replace, comments add, and formatting commands.

Mutating commands

superdoc comments add [<doc>] --target-json '{...}' --text "Please revise" [--out ./with-comment.docx]
superdoc replace [<doc>] --target-json '{...}' --text "Updated text" [--out ./updated.docx]
superdoc format bold [<doc>] --target-json '{...}' [--out ./bolded.docx]

• In stateless mode (<doc> provided), mutating commands require --out.
• In stateful mode (after open), mutating commands update the active working document and --out is optional.
• Use --expected-revision <n> with stateful mutating commands for optimistic concurrency checks.

Low-level invocation

superdoc call <operationId> --input-json '{...}'

• Invokes any document-api operation directly with a JSON payload.

Save command modes

superdoc save --in-place
superdoc save --out ./final.docx

• save persists the active session but keeps it open for more edits.
• If no source path exists (for example stdin-opened docs), save requires --out <path>.
• save --in-place checks for source-file drift and refuses overwrite unless --force is passed.

Close command modes

superdoc close
superdoc close --discard

• Dirty contexts require explicit --discard (or run save first, then close).

Output modes

• Default: --output json (machine-oriented envelope)
• Human mode: --output pretty (or --pretty)

superdoc info ./contract.docx --output json
superdoc info ./contract.docx --pretty

Global flags

• --output <json|pretty>
• --json
• --pretty
• --session <id>
• --timeout-ms <n>
• --help

Input payload flags

• --query-json, --query-file
• --address-json, --address-file
• --target-json, --target-file

Stdin support

Use - as <doc> to read DOCX bytes from stdin:

cat ./contract.docx | superdoc open -
cat ./contract.docx | superdoc info -

JSON envelope contract

Normative operation/version metadata comes from @superdoc/document-api; use superdoc describe for the runtime contract surface.

Success:

{
  "ok": true,
  "command": "find",
  "data": {},
  "meta": {
    "version": "1.0.0-alpha.2",
    "elapsedMs": 42
  }
}

Error:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "..."
  },
  "meta": {
    "version": "1.0.0-alpha.2",
    "elapsedMs": 8
  }
}