Revise CLI

Read, edit, and redline Word documents. Available as CLI and TypeScript library.

npx revise

For Agents#

The revise CLI makes AI agents faster and cheaper.

Claude Code and Codex finish the same document tasks about 1.5-2× faster and using 30-70% less usage compared to their default docx toolset. See our benchmarks on GitHub.

Read https://revise.io/skills/cli.md and follow it.

Install#

npm i -g revise

Global options:

• --json: one machine-readable object per command; see JSON output.
• --author <name> (or REVISE_AUTHOR): sign tracked changes.
• --no-color: plain text. Output is colored only on a terminal, and never with --json. NO_COLOR=1, TERM=dumb, and FORCE_COLOR=0 turn it off; FORCE_COLOR=1 turns it on even in a pipe.
• --help: help for a command, e.g. revise render --help.

Results go to stdout. Warnings and errors go to stderr as warning[code]: … and error[code]: …, often with a hint: command to run next.

Exit codes: 0 done (including nothing to do), 1 failed and nothing was saved, 2 partly done (some of it was saved; the error says what wasn't), 70 internal error or a save whose outcome is uncertain.

Reading#

read, grep, and search show pending tracked changes: read marks them <del data-change-id="…" data-author="Jane Smith">100</del><ins …>120</ins>, and grep writes them [-100-]{+120+} and finds text on either side, saying which matches are in deleted or inserted text. search adds the blocks whose deleted text matches. --view accepted reads the text as if every change were accepted (what the editing tools edit), --view original as if every one were rejected. Tracked HTML pasted back into a tool edits the accepted text: <ins> reads as its text and <del> is left out.

Editing#

Edits save the file. To keep it as it is, add --out new.docx to replace-all, call, accept, reject, or xml patch: the result is saved as the new file (same format; --force replaces an existing one), and block ids read from the original work on it. The copy has its own history, starting from the original, so undo steps back to it.

The tools are the ones the Revise agent uses: replace, insert_block, replace_block, remove_blocks, style_blocks, leave_comment, insert_footnote, table row, column, and cell tools, set_header_footer, set_page_layout, and the read and search tools. revise tools <name> prints a tool's JSON schema.

revise call contract.docx replace - <<'JSON'
{"id": "p-12", "replacements": [{"find": "thirty", "replace": "sixty"}]}
JSON

Review#

--dry-run on accept and reject lists what would be settled.

A section is a heading and everything under it until the next heading at its level or above. Numbers work whether they're typed or Word's automatic numbering, as outline shows them. A title matches when typed in full, or by any part of it that's in only one heading; text in several headings is an error, never a guess. --section, --except-section, and --blocks combine. read and replace-all take block ids only (--ids is the older name).

Output#

Create and convert#

Pipes#

- as the input reads the document from stdin, and - as the output writes it to stdout:

cat notes.md | revise convert - notes.docx           # format recognized from the bytes
curl -s https://example.com/page | revise convert - page.docx
revise convert contract.docx - | grep -i liability   # stdout is Markdown by default
revise convert contract.docx - --to html > contract.html
revise convert contract.docx - --to docx | ssh host 'cat > copy.docx'

On stdin, revise recognizes .docx and .odt from their zip entries, and RTF and HTML from how they start (after any leading whitespace or comments). Any other text reads as Markdown, which plain text already is. Text that opens with <!doctype html>, <html>, <head>, or <body> is HTML. Text that opens with any other tag is HTML too, unless the rest of it writes Markdown (# headings, code fences, links, *emphasis*), like a README under its banner; lists count as Markdown only when no HTML block is closed. Text may be UTF-8, UTF-16, or Windows-1252, recognized or named. When a guess would be wrong, --from settles it. --from md|txt|html|rtf|odt|docx names the format instead, for example --from txt to keep a line starting with # as text. --to md|html|txt|docx|pdf picks stdout's format. A .docx or PDF won't print to a terminal, and --json can't be combined with - as the output, because both would need stdout.

Names from 3.0#

These still work, so scripts written for 3.0 keep running:

Raw package#

For what the tools don't cover: style definitions, numbering, settings, document properties.

Patches apply directly to the file, and undo reverts them.

Agents#

See agents.