Command-line editing

Read and edit Word, Excel, PowerPoint and PDF files from a terminal or a script.

Install

The tumbler command needs Bun 1.3 or later. It uses the same engines as the editors, so an edit made here matches one made in the UI.

Terminal
bun add --global @tumblerjs/cli
tumbler --help
tumbler draft.docx --help

Help is generated from the operations each file type supports, so tumbler <file> --help always lists what you can do to that file.

Terminal
tumbler create draft.docx
tumbler draft.docx read
tumbler draft.docx inspect --input '{"what":"styles"}'

Read, then edit

read prints the document with a handle for each page. Pass a handle from a fresh read to your edit, so the edit applies to the version you looked at.

Terminal
tumbler draft.docx replace --page '<handle from read>' --find 'draft' --value 'final'
tumbler draft.docx format --help
tumbler draft.docx edit-object --help

An edit fails without writing anything when:

  • an input is not recognised;
  • the text you are looking for matches in more than one place;
  • the file changed since you read it.

The file is locked while it is written, and replaced in one step, so a failed write never leaves half a file.

Word files support structured edits to headers and footers, formatting, styles, lists, tables, drawings and ink. Spreadsheets and presentations accept the same commands as applySpreadsheetCommand and applyPresentationCommand. Run --help on an operation to see its fields, units and examples.

Replacement text

FlagReads
--value textThe text, with \n, \r, \t and \\ turned into a newline, carriage return, tab and backslash.
--value text --literalThe text exactly as typed, backslashes included.
--value-file pathThe exact contents of a UTF-8 file, including trailing newlines.
--value-file -The same, from standard input.
Terminal
tumbler draft.docx replace --page '<handle>' --find old --value-file replacement.txt

Empty replacement text deletes the target. JSON passed with --input follows normal JSON escaping only.

PDF pages

Terminal
tumbler source.pdf export --pages 3,1-2 --output selected.pdf
tumbler report.pdf pdf delete-pages --help
tumbler first.pdf pdf merge --source second.pdf --output merged.pdf
  • Page numbers start at 1, and a range such as 1-2 includes both ends.
  • export writes the pages you list to a new file, in the order you list them.
  • delete-pages edits the file in place. It cannot delete every page, and rejects PDFs with attachments, metadata or page labels.
  • merge can repeat pages and files.

Deleting pages is not redaction. Do not rely on it to remove sensitive content.

Merge PDF pages โ†’

Charts

charts read lists a file's charts and their source data. charts edit changes a chart's data or properties, and fails if the chart changed since you read it. Both work on DOCX, XLSX and PPTX files.

Terminal
tumbler report.docx charts read
tumbler report.docx charts edit --help

Charts โ†’

Full command reference โ†’