DraftAgent

DraftAgent CLI for DOCX Automation

DraftAgent includes a native command-line interface for inspecting Word documents, applying structured transformations, and converting DOCX files to DOCX, HTML, or PDF.

For installation and general setup, see the DraftAgent documentation. This page describes the command-line contract and the currently supported options.

Compatibility note: DraftAgent converts documents into its canonical document model. Unsupported source XML and package parts are not preserved. Validate output with your documents before relying on the CLI in production workflows.

Installation

Install the CLI with Homebrew:

brew install draftagent/tap/draftagent-cli

The installed binary is named draftagent:

draftagent inspect input.docx
draftagent transform input.docx \
  --replace "Draft" "Final" \
  --output /tmp/transformed.docx

Commands

inspect

Reads a DOCX and prints package and parsed-model information. Use --elements to list document elements and their session-scoped IDs.

draftagent inspect input.docx --elements --detail full --json

The --detail option applies to element output:

  • outline lists the element structure and IDs;
  • text adds text content; and
  • full also includes run-level information and selector-ready model paths.

Inspection can include paragraphs, tables, rows, cells, images, unsupported blocks, styles, and effective formatting information. The JSON output is suitable for scripts and for finding IDs needed by structural transform options.

convert

Converts a DOCX to canonical DOCX, HTML, or PDF output. The output extension selects the format:

  • .docx — canonical OOXML;
  • .html or .htm — HTML;
  • .pdf — PDF; and
draftagent convert input.docx --output /tmp/document.html
draftagent convert input.docx --output /tmp/document.pdf

create

Starts with a blank document and optionally appends paragraphs. The command creates a valid DOCX when the output has a .docx extension.

draftagent create \
  --paragraph "Title" \
  --paragraph "Created from scratch" \
  --output /tmp/new-document.docx

Repeat --paragraph to add multiple paragraphs. Use an empty string when you need an intentional blank paragraph.

transform

Applies transformations to an input DOCX and writes the result to the requested output path. Convenience flags can be combined and are applied in command order where supported.

draftagent transform input.docx \
  --replace "Draft" "Final" \
  --set-run-style "Final" \
  --append-paragraph "Approved" \
  --output /tmp/transformed.docx

The output extension selects the result format, so transformations can also produce HTML or PDF:

draftagent transform input.docx \
  --replace "Draft" "Final" \
  --output /tmp/transformed.html

Common options

All commands support --json for a machine-readable success summary. Human-readable status messages are the default. Warnings and diagnostics are written to stderr.

draftagent --json transform input.docx \
  --replace Draft Final \
  --output output.docx

Additional global and command options include:

  • --performance, which prints elapsed execution time to stderr;
  • --strict on create and transform, which treats transformation warnings as errors; and
  • --output OUTPUT, which selects the destination path and, for conversion and transformation, the output format by extension.

The convert and create commands create missing parent directories. The CLI writes only the requested output path and does not leave preview PDFs or other additional artifacts.

Transform options

The CLI supports text replacement, character and paragraph formatting, lists, structural edits, and selected table operations.

Text and formatting

  • --replace SEARCH REPLACEMENT replaces all matching occurrences and may be repeated;
  • --append-paragraph TEXT appends a paragraph and may be repeated;
  • --set-run-style TEXT applies bold styling to matching runs;
  • --italic TEXT and --underline TEXT apply character styling to matching runs;
  • --font TEXT FONT, --font-size TEXT POINTS, and --color TEXT COLOR apply character formatting to matching runs;
  • --paragraph-alignment BLOCK_ID ALIGNMENT accepts left, center, right, or justify;
  • --paragraph-spacing BLOCK_ID BEFORE AFTER LINE sets spacing in twentieths of a point;
  • --heading BLOCK_ID LEVEL applies a heading level from 1 through 9; and
  • --replace-paragraph BLOCK_ID TEXT replaces paragraph runs while preserving the paragraph ID.

For example:

draftagent transform input.docx \
  --italic "Important" \
  --font "Important" "Aptos" \
  --font-size "Important" 14 \
  --color "Important" "1F4E79" \
  --paragraph-spacing el_42 120 240 276 \
  --heading el_42 2 \
  --output /tmp/formatted.docx

Lists

  • --bulleted-list BLOCK_ID and --numbered-list BLOCK_ID convert paragraphs to lists and may be repeated;
  • --list-level BLOCK_ID LEVEL changes list nesting, starting at level 0;
  • --remove-list BLOCK_ID removes list formatting;
  • --insert-list-item ANCHOR_ID TEXT inserts a list item;
  • --move-list-item ITEM_ID BEFORE_ID moves a list item; and
  • --delete-list-item ITEM_ID deletes a list item.

Structural blocks

  • --insert-paragraph-before BLOCK_ID TEXT and --insert-paragraph-after BLOCK_ID TEXT insert paragraphs;
  • --delete-block BLOCK_ID deletes a block;
  • --move-block-before BLOCK_ID DESTINATION_ID and --move-block-after BLOCK_ID DESTINATION_ID move blocks; and
  • --replace-paragraph BLOCK_ID TEXT replaces paragraph content while preserving its element ID.

Empty paragraphs are supported by paragraph creation and insertion options. Use an empty string for a deliberate blank paragraph.

Tables

The CLI currently supports selected table edits:

  • --add-table-row TABLE_ID and --delete-table-row TABLE_ID ROW_ID;
  • --add-table-column TABLE_ID INDEX and --delete-table-column TABLE_ID INDEX;
  • --set-cell-text CELL_ID TEXT;
  • --merge-cells TABLE_ID ROW START_COLUMN END_COLUMN; and
  • --split-cell CELL_ID.
draftagent transform input.docx \
  --add-table-row el_100 \
  --add-table-column el_100 1 \
  --set-cell-text el_101 "Updated value" \
  --output /tmp/table.docx

Table creation, table widths, borders, shading, and path-based selectors are not currently exposed as convenience flags. Use the MCP interface or library APIs for those capabilities.

Element IDs and selectors

Use inspect --elements to find IDs for structural options:

draftagent inspect input.docx --elements --detail outline

An ID such as el_42 is valid only for the loaded document model and its transformation lineage. IDs are not stable across a new invocation or a new document load. The current CLI options primarily accept element IDs rather than MCP-style path selectors. Paths are included in JSON inspection output for identifying elements and for use in operation manifests.

Ordered operation manifests

Use transform --operations PATH to apply a JSON operation manifest in array order. Each operation is resolved against the document state produced by the preceding operation, and the output is written only after the complete manifest succeeds.

A manifest may be a JSON array or an object containing an operations array:

{
  "operations": [
    {"op": "appendParagraph", "text": ""},
    {
      "op": "insertParagraph",
      "position": "after",
      "target": "sections[0].blocks[0]",
      "paragraph": {"text": "Invoice totals"}
    },
    {
      "op": "applyParagraphFormat",
      "target": "sections[0].blocks[1]",
      "style": {
        "spacing": {"before": 120, "after": 240, "line": 276, "lineRule": "auto"}
      }
    }
  ]
}

Manifest targets may be element IDs or model paths. Paragraph operations accept plain text shorthand or a structured paragraph object with text or runs.

The currently supported manifest operation IDs are:

  • replaceText
  • appendParagraph
  • insertParagraph
  • deleteBlock
  • replaceParagraphContent
  • setHeadingLevel
  • setRunFormat
  • applyRunFormat
  • applyParagraphFormat
  • setCellText
  • addRow
  • addColumn
  • deleteColumn
  • splitCell

Unsupported operation IDs fail with the operation index and do not write an output file. The manifest format follows the same operation naming conventions as the MCP interface, but CLI manifest coverage is currently only a subset of the MCP catalog.

Output and warnings

With --json, successful transform output includes the output path, format, applied transforms, and warnings. Human-readable diagnostics are printed to stderr, and CLI errors are currently human-readable rather than MCP-style structured JSON errors.

PDF conversion can emit font-substitution and other renderer warnings on stderr when a requested font is unavailable. For example, Calibri may be replaced by Carlito. These warnings do not mean conversion failed. Use --strict where supported if warnings should fail the command.

CLI and MCP

The CLI and MCP server share the canonical document model and transformation implementations. They are separate interfaces with different coverage:

  • the CLI provides shell-friendly convenience flags and a partially supported ordered manifest;
  • MCP exposes a broader structured operation catalog and path-aware request schemas; and
  • a capability available through MCP is not necessarily available as a CLI flag or manifest operation.

Use the CLI for local scripts and automation, and use MCP when an agent needs runtime tool discovery, structured selectors, or the broader transformation catalog.