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.
bun add --global @tumblerjs/cli
tumbler --help
tumbler draft.docx --helpHelp is generated from the operations each file type supports, so tumbler <file> --help always lists what you can do to that file.
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.
tumbler draft.docx replace --page '<handle from read>' --find 'draft' --value 'final'
tumbler draft.docx format --help
tumbler draft.docx edit-object --helpAn 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
| Flag | Reads |
|---|---|
--value text | The text, with \n, \r, \t and \\ turned into a newline, carriage return, tab and backslash. |
--value text --literal | The text exactly as typed, backslashes included. |
--value-file path | The exact contents of a UTF-8 file, including trailing newlines. |
--value-file - | The same, from standard input. |
tumbler draft.docx replace --page '<handle>' --find old --value-file replacement.txtEmpty replacement text deletes the target. JSON passed with --input follows normal JSON escaping only.
PDF pages
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-2includes both ends. exportwrites the pages you list to a new file, in the order you list them.delete-pagesedits the file in place. It cannot delete every page, and rejects PDFs with attachments, metadata or page labels.mergecan repeat pages and files.
Deleting pages is not redaction. Do not rely on it to remove sensitive content.
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.
tumbler report.docx charts read
tumbler report.docx charts edit --help