word-cli

Your Word documents, AI-ready. Read, edit, and update without leaving the terminal—or let your AI agent do it for you.

Zero-config Word integration. JSON in, JSON out. Any shell-capable agent can use it.

---

Who Is This For

Office Power Users	AI Agent Developers
Edit reports, contracts, proposals with AI assistance	Integrate Word into agent toolchains
Batch-edit multiple documents via scripts	No MCP server, no protocol setup
Use selection-based editing (select → AI rewrites)	JSON stdout, structured errors, exit codes

---

Use Cases & Scenarios

For Office Power Users

• Contract review: Open a contract, run get-content → send to AI for review → apply suggested changes with update-paragraph
• Report drafting: Select a section in Word, run get-selected-text → AI rewrites → apply with update-selected-text
• Template filling: insert-after-text --search-text "{{placeholder}}" --text-to-insert "actual content"
• Batch document processing: Script loops over .docx files, applies AI edits, saves with save-document

For AI Agent Developers

• RAG over Word: Agent runs word get-content --file doc.docx, parses JSON, feeds to LLM context
• Document editing agent: Agent reads content → generates edits → runs update-paragraph / update-selected-text → save-document
• Cursor/IDE integration: Custom command that runs word get-content and pastes into chat
• MCP alternative: No server to run; any tool that can exec a command can use word-cli

---

Why CLI Over MCP?

• No server process to manage or keep alive
• No protocol configuration — just shell commands
• Works everywhere: shell scripts, Python subprocess, Node child_process, any IDE that runs commands
• If your agent can run word get-content --file doc.docx, it can read Word.

---

Install

Clone the repo, then:

cd word-cli
uv tool install .

Requires Microsoft Word installed (Windows). Works with Office 2016+.

---

Quick Start

1. Open Microsoft Word (or let word-cli start it).
2. Run word list-documents to see open documents.
3. Run word get-content --file C:\path\to\document.docx to read content.
4. Run word update-paragraph --document-id "C:\path\to\doc.docx" --paragraph-index 1 --text "New text" to update.

One-liner for agents (extract full content):

word get-content --file report.docx | jq .full_content

---

Typical Agent Workflow

# 1. Open document
word open-document C:\docs\report.docx

# 2. Get content (agent parses JSON)
word get-content --document-id "C:\docs\report.docx"

# 3. Update paragraph (after AI suggests edit)
word update-paragraph --document-id "C:\docs\report.docx" --paragraph-index 3 --text "Revised paragraph"

# 4. Save
word save-document --document-id "C:\docs\report.docx"

---

Usage

General

word --help

Commands

Command	Description	Agent Use
list-documents	List all open Word documents	Discover open docs
open-document	Open a document by path	Open before read/write
get-content	Get document content and paragraphs	Read — primary input for agents
get-selected-text	Get currently selected text	Read — selection-based input
update-paragraph	Update a paragraph by index	Write — edit by paragraph
update-selected-text	Replace selection with new text	Write — edit selection
insert-after-text	Insert text after a search string	Write — template filling
save-document	Save document (optionally to new path)	Lifecycle — persist changes
close-document	Close document (with optional save)	Lifecycle — cleanup

Examples

List open documents:

word list-documents

Open a document:

word open-document C:\path\to\document.docx

Get content (by file or document-id):

word get-content --file C:\path\to\document.docx
word get-content --document-id "C:\path\to\document.docx"

Update a paragraph:

word update-paragraph --document-id "C:\path\to\doc.docx" --paragraph-index 1 --text "New paragraph text"

Get selected text:

word get-selected-text
word get-selected-text --document-id "C:\path\to\doc.docx"

Update selected text:

word update-selected-text --text "Replacement text"

Insert after specific text:

word insert-after-text --search-text "Chapter 1" --text-to-insert "Content here"

---

Agent Integration

word-cli is designed for easy integration into AI agents and automation tools.

JSON by Default

All commands output JSON to stdout. Easy to parse with jq, Python, Node, or any JSON library.

Error Contract

• Errors: {"error": "..."} written to stderr, exit code 1
• Success: JSON to stdout, exit code 0
• Use --verbose or -v for debug logs to stderr

Document Selection

• --file PATH: Path to a Word document (opens if not already open)
• --document-id ID: Document ID from list-documents or open-document (usually the file path)

Output to File

Use --output FILE or -o FILE to write JSON to a file instead of stdout.

Agent Flow

flowchart LR
    Agent[Agent] -->|word get-content| Word[Word CLI]
    Word -->|JSON stdout| Agent
    Agent -->|LLM process| LLM[LLM]
    LLM -->|edit instructions| Agent
    Agent -->|word update-paragraph| Word
    Word -->|success JSON| Agent

Loading

---

Requirements

• Windows (Microsoft Word + pywin32 COM automation)
• Python >= 3.10