GenOffice Document CLI

genoffice — GenOffice from the terminal

genoffice is installed with GenOffice. Run genoffice --version first. If the command is not found, GenOffice writes the launcher directory to ~/.genoffice/launcher (Windows: %USERPROFILE%\.genoffice\launcher) on every start: read that one line and run "<dir>/genoffice" from bash or "<dir>\genoffice.cmd" from PowerShell / cmd, quoted, in place of genoffice below. Default locations when that file is missing: macOS /Applications/GenOffice.app/Contents/Resources/cli, Windows %LOCALAPPDATA%\Programs\GenOffice\resources\cli, Linux /opt/GenOffice/resources/cli. Every command runs headless on the app's own engines; only search, image and media send data off the machine, to the provider configured in GenOffice.

Always add --json when a program reads the output: one JSON object on stdout, { "status": "ok" | "partial", "command", "summary", "output_path"?, "warnings"?, "detail"? } (partial: an apply with --best-effort / --stop-on-error wrote the file but lost ops) or { "status": "error", "code", "error", "message", "suggestion"?, "detail"? }. Exit codes: 0 ok, 1 usage or rejected ops, 2 file not found / output exists / file open in GenOffice, 3 conversion failed, 4 app not available. error is the machine-readable reason (table under "When a command fails"), suggestion the next step in one sentence, including did you mean "…"? when a command, option, op name, element id or sheet name is one typo away. detail carries facts as fields (failures[] with index, op, error, reason, valid_range, available, supported, usage; sheets, options, commands); never parse message.

Commands

--ops - and --cells - read stdin. --out defaults to the input file's folder with the new extension (convert) or edits in place (apply). Unknown options are rejected (exit 1). The mcp server runs on stdio by default; mcp [--http <port> [--host <addr>] [--token <secret>]] serves Streamable HTTP instead; genoffice mcp install <agent|all> [--dir <path>] [--force] registers the stdio server in a coding agent's MCP config (mcp uninstall <agent> removes it, mcp list shows each agent).

genoffice mcp as an MCP client sees it:

• Tools mirror the commands one-to-one (info, convert, create_docx / create_xlsx / create_pptx / create_pdf, docs_read / docs_apply / docs_check, sheet_read / sheet_apply / sheet_check, slides_read / slides_apply / slides_audit / slides_render / slides_check / slides_replace, render, guide, capabilities, search, image, media, open, selection); ops, cells, specs and Markdown go inline, results are the --json envelope (a partial batch is not isError, its first text block lists the lost ops), open and selection exist on stdio only.
• deck_start / deck_page / deck_build / deck_replace are the staged deck flow above with the deck folder as state; a short deck with concrete content is one create_pptx call.
• The op references are resources: genoffice://guide/docs, …/sheets, …/slides, …/slides/design, …/slides/spec.
• ops, cells and data carry the per-op schema of guide <domain> --json (one variant per op: op, fields, required); mcp --compact-schemas (or GENOFFICE_MCP_COMPACT_SCHEMAS=1) advertises plain arrays for clients with a small context budget.
• --http: files travel with the calls (PUT /files/<name> uploads one and returns a URL, every path parameter also takes an http(s) URL, out omitted returns the file as a download URL).
• The GenOffice app runs its own MCP server on 127.0.0.1:3093 (Settings → Integrations) whose tools (create_session, read_document, apply_ops, apply_slide_ops, apply_sheet_ops, read_pdf, open_documents) edit the documents already open in the visible editor; genoffice mcp works on files on disk.

Which command

Behaviour to know

• Word (docs): block indexes inside one batch are live — after insert_content adds two blocks, later indexes shift by two. A target that matches no block fails the whole batch (exit 1). findReplace does not reach table cells (use replace_blocks on the table). Tags outside the restricted set are stripped silently. convert docx→md writes GFM: & < > become entities, formulas become $…$, images are dropped and counted in detail.skipped. create --from x.md embeds local images referenced by relative path. insert_image takes a local path (relative to the current directory, then to the ops file), a data: URL or an http(s) URL (png/jpg/gif) and appends unless afterBlockIndex is given; edit_chart targets blocks docs read lists with kind chart; set_header_footer writes plain text with {PAGE} / {NUMPAGES} tokens, view: "first" switches the different-first-page setting on; comment ids come from docs read --comments; add_comment anchors a new thread to a block or to an exact text span inside it (occurrence picks one of several matches) without touching the document text; delete_comment on a thread root with replies needs withReplies: true; revision ids (r1, r2, …) come from docs read --revisions and are positional, so read again after any edit before accept_changes / reject_changes. insertField computes SEQ numbers, REF text, DATE and MERGEFIELD locally; PAGE / NUMPAGES / AUTHOR-style results are placeholders Word recomputes on open (docs check reports them as info), so say so when you hand over the file. Note ids for edit_note / delete_note come from docs read --notes; edit_note is findReplace inside one note ({ id, find, replace, matchCase? }, kind only when a footnote and an endnote share the id) and keeps the note's id, reference mark and formatting — findReplace itself never reaches note text. define_style patches only the fields given (an existing style keeps the rest); applyStyle takes a paragraph style id from docs read --styles and turns blocks into headings when the style is a heading style; set_watermark with text: null removes the watermark; insert_picture / insert_text_box lengths take 2.54cm / 1in / 72pt / 96px or points. set_page_setup changes paper / orientation / margins / columns / titlePg / page numbering of every section or of one (section: N or blockIndex), lengths as "2.54cm" / "1in" / "72pt"; insert_section_break splits a section after a block (the copy is then changed with set_page_setup section: N); docs read --sections lists sections with their block ranges. Native tables take structure ops: insertTableRow / deleteTableRow / insertTableColumn / deleteTableColumn (0-based, position: "before"|"after", count), mergeTableCells / splitTableCell (grid range / cell; a merge that cuts an existing merged cell is refused), setTableCellFormat (fill, vAlign, borders, width in twips or "2.5cm"), setTableStyle (a style id from docs read's tableStyles, plus look flags); target them with nodeType: "table" and docs read shows each table's rows, cols and merged cells.
• Excel (sheet): ops run in order, each seeing the previous result: after insert_rows/delete_cols the following ops address the shifted grid (a formula written after the shift is stored as given, one written before it is shifted like the existing ones), a sheet added or renamed earlier in the batch is addressed by its new name; rules, links, notes, filters and visuals must come after any row/column op on their sheet, and defined-name ops cannot share a batch with sheet or row/column ops. set_cell with a string starting with = writes a formula; type: "text" keeps it literal text. Beyond cells, sheet apply --ops writes charts (add_chart, edit_chart on xl/charts/chartN.xml), images and shapes, Excel tables, freeze panes, hidden rows/columns, filters with checked values, conditional formats, data validation, hyperlinks, notes, page setup, sheet protection, defined names and tab order/visibility (genoffice guide sheets has every field). --cells style takes the same object as format_range.format ({bold, fillColor, numberFormat, …}). Colors are #RRGGBB or theme slots that follow the workbook theme: "accent1", "accent1+40%" (lighter), "dk2-25%" (darker) or {theme, tint}; fill: {pattern: "lightGray", fg, bg?} or fill: {gradient: {angle, stops: [{position, color}]}} writes pattern and gradient fills, and --formats echoes them back with the slot, tint and resolved rgb. sheet read returns raw values (0.25, serial dates) and formulas separately, features (sheet-wide panes, filter, charts, tables and rule counts; merges and links of the range), and with --formats the styled cells, column widths (px) and row heights (pt); convert --to csv returns the displayed text (percent, dates), UTF-8 with BOM, CRLF line ends, active sheet unless --sheet. create --from x.csv: a sep=; first line is honoured, ISO dates (2024-01-01, 2024-01-02 09:30) become real dates with a date format, --decimal , reads 1.234,5 as 1234.5. Formulas using functions the local engine cannot evaluate (FILTER, SORT, UNIQUE, LET, …) are written without a cached value and Excel computes them on open; spill formulas are stored as dynamic arrays so they spill in Excel 365; the formulas_not_cached warning names those cells.
• PowerPoint (slides): picture ops (addPicture, replacePicture, addMedia, setImageFill, setBackground) take a local path or data URL in bytes; the extension is inferred. setText runs inherit the element's first run style unless a field is set explicitly (bold: false). Ops in one apply batch run in order, so a later op may target a slide an earlier op added; atomic still writes nothing unless every op applied; --best-effort (formerly --isolation per_op) and --stop-on-error write what applied and answer status: "partial". Created elements get new e_* ids: run slides read again before targeting them. convert pptx→pdf is rendered like the app's export: one bitmap per slide, no text layer. Every EMU length field (box, offset, dx/dy, wEmu/hEmu, colWidthsEmu, insets) also takes a string with a unit suffix: "2.54cm", "1in", "10mm", "12pt", "96px". slides read lists each page's animations[] (seq, el, effect, kind, trigger, durationMs, delayMs, direction); addAnimation / removeAnimation / reorderAnimation edit one timeline item (presetXml passes a PowerPoint-exported effect through verbatim), insertEquation adds a typeset formula from LaTeX (PowerPoint renders it, previews show the linear text).
• Conversions in the app (→pdf, docx→html, html→docx, create --type pdf, render): a hidden GenOffice process per call, 1–6 s, up to 180 s timeout, safe to run concurrently. html→docx is html2docx for real web pages; a restricted-HTML fragment with <formula> goes through create --type docx --from fragment.html instead.
• Cloud (search, image, media): --images returns detail.images[] {title,imageUrl,sourceUrl,source,width,height}; providers may return fewer than --max. image saves with the provider's real format (output_path tells you; a .png request may come back .jpg, noted in detail.note); --aspect / --size are validated locally.