Genoffice

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).

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 delete_note come from docs read --notes. 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. 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.

Workflow

1. genoffice info or genoffice <domain> read --json to learn the structure: block indexes (docx), s_<n> / e_* ids and EMU geometry (pptx), sheet names and cell values (xlsx).
2. genoffice guide <domain> for the op fields (guide <domain> <op> --json for one op's schema), then write the ops JSON yourself.
3. genoffice <domain> apply --dry-run when the batch is large; a rejected op comes back as op_rejected with the executor's usage line — fix that op and resend the whole batch. Atomic by default: on rejection the file is untouched and detail.batch is {total, applied: 0, failed, skipped}. --best-effort applies every op that can apply, --stop-on-error applies in order up to the first rejection; both write the file and answer status: "partial" (exit 0) with the lost ops in detail.failures and the counts in detail.batch — a program must check status, not only the exit code.
4. The QA gate below, then report the output path.

Pitfalls

When a command fails

Branch on error, do what suggestion says, then resend the whole batch (atomic apply wrote nothing). detail has the facts as fields, never parse message.

A successful result may still carry warnings[] ({code, message, suggestion?}): formulas_not_cached, op_warning (a sheets op was adjusted), images_dropped (convert docx→md), output_renamed (image saved with the provider's real extension). Read them, report what matters, do not retry.

Before you say "done"

Three lines per artifact, every time:

check/audit exit 0 whether or not they found something; the findings are in detail.issues[] with a stable code, a path and, when possible, a suggest op to pass to apply as is. Do not run genoffice open unless the user asks to see the file in GenOffice.

Reading the user's files

Source material the user hands you (a report to turn into slides, a workbook to summarize) is read by you, not by genoffice: md, txt, csv, pdf and images you open directly. Office files are zipped XML, so go through the CLI first:

• docx: genoffice convert file.docx --to md --out file.md for the whole text (images are dropped), or genoffice docs read file.docx --full --json / --html for blocks with indexes.
• xlsx: genoffice convert file.xlsx --to csv --sheet <name> --out file.csv for a whole sheet as displayed text, or genoffice sheet read file.xlsx --range A1:H200 --json for raw values (without --range it stops at 500 rows and says truncated: true; --stats first to size a workbook, --cols/--max-rows to page through a wide or long sheet, --where formula for the formulas alone).
• pptx: genoffice slides read file.pptx --full --json for every slide's text, tables and speaker notes; genoffice slides render file.pptx --out shots when you need to see the pages.

Take figures and wording from that material; never cat or unzip the Office file itself.

Designing a deck

Whenever the user wants a presentation, however short, do not hand-place ops: follow the staged pipeline the GenOffice app itself uses. You are the model, genoffice is the engine, and each stage is a file the CLI checks before the next one starts. Ops (create --ops, slides apply) are for editing a deck that already exists.

1. genoffice guide slides design once per session, then genoffice guide slides spec. Run genoffice capabilities --json once: it says whether search, image search and image generation are configured in GenOffice; use them for facts and photos only when they are, and plan photo-free pages otherwise.
2. Make a folder for the deck. Write the style sheet to deck/style.md (colors, fonts, layout variants, one sentence of style). Then the outline to deck/outline.json (core hook + one entry per page: title, type, layout, brief with real figures, image_queries) and run genoffice slides check deck/outline.json --json; fix every error before going on. Show the outline to the user only if they asked to review it.
3. One page per step: re-read deck/style.md and the page's outline entry, resolve its photos, write deck/pages/NN.json (one page object echoing the entry's title, type, layout), run genoffice slides check deck/pages/NN.json --json; it finds outline.json and style.md one folder up and checks the page against entry N and the palette. Fix until detail.audit, detail.outline.findings and detail.style.offPalette are empty (a disagreement with the outline exits 1), then the next page. Never write several pages in one file or one step.
4. genoffice create --type pptx --spec deck/pages --outline deck/outline.json --out deck/deck.pptx --json (refuses to run while an outline page has no file or a page disagrees with its entry). Then genoffice slides render deck/deck.pptx --out deck/shots --json and look at the PNGs; genoffice slides audit deck/deck.pptx --json for the geometry findings. Fix a page in its file and genoffice slides replace deck/deck.pptx --slide n --spec deck/pages/NN.json --json. At most two fix rounds.
5. Report the path. Photos come from genoffice search --images results, genoffice image, or local files the user gave you; never draw a grey box in place of a photo. Figures come from the user's material or genoffice search; say so when a number is illustrative.

Editing an existing deck

A rewrite of one slide, a new title, a swapped picture: use ops, not the staged pipeline, and keep the deck's own design.

1. genoffice slides read deck.pptx --slide n --full --json for the element ids and the current text; genoffice slides render deck.pptx --slide n --out shots --json when the words alone do not tell you what the page looks like.
2. setText on the existing element (runs you leave unstyled inherit the original font, size and color), addElement / addPicture for new content, deleteElement for what goes. Write with --out when the user wants the original kept.
3. genoffice slides audit deck.pptx --slide n --json after the edit: a longer sentence in the same box overflows; apply the suggest ops it returns (they grow or move the box), then render once more and look.
4. Ids of edited elements change: run slides read again before a second round of ops. slides replace --slide n --spec rebuilds the page from a spec and is for decks the staged pipeline built, not for restyling a deck the user brought.

Examples

Deck from ops (an existing deck's edits, or a fixture; a presentation for a person goes through the staged path above):

jsonCopy code
[
  {
    "op": "addElement",
    "target": { "slide": 0 },
    "kind": "textbox",
    "offset": { "x": 914400, "y": 685800, "cx": 7315200, "cy": 914400 },
    "paragraphs": [{ "runs": [{ "text": "Q3 Review", "bold": true, "fontSize": 36 }] }]
  },
  { "op": "addBlankSlide", "target": { "slide": 0 } },
  {
    "op": "addTable",
    "target": { "slide": 1 },
    "rows": 3,
    "cols": 3,
    "offset": { "x": 914400, "y": 1828800, "cx": 7315200, "cy": 2286000 }
  }
]

Copy code
genoffice create --type pptx --ops deck.json --out q3.pptx --json

Workbook with formulas, then a formatted header:

Copy code
echo '[["item","qty","price"],["Apple",2,1.5],["Total","=SUM(B2:B2)",""]]' > table.json
genoffice create --type xlsx --from table.json --out sales.xlsx
echo '[{"op":"format_range","range":"A1:C1","format":{"bold":true,"fillColor":"#FFFF00"}}]' | genoffice sheet apply sales.xlsx --ops - --json

Word from Markdown, then insert a paragraph after block 0:

Copy code
genoffice create --type docx --from report.md --out report.docx
echo '[{"op":"insert_content","afterBlockIndex":0,"html":"<p>Executive summary.</p>"}]' | genoffice docs apply report.docx --ops -

Path rules

• Pass absolute paths or paths relative to the current directory; genoffice never writes outside the --out path or the file being edited.
• create and convert refuse to overwrite an existing output without --force. apply edits in place unless --out is given; --out onto another existing file also needs --force.
• genoffice refuses to rewrite a file the GenOffice window currently has open (exit 2, message "GenOffice has this file open"). Ask the user to close that tab, write to another path with --out, or pass --force only if they accept that the editor may overwrite the change.
• If GENOFFICE_ALLOWED_ROOTS is set in the environment, genoffice only reads and writes inside those directories (exit 2 otherwise); stay within them. Every executed command is logged to ~/.genoffice/cli-audit.jsonl (GENOFFICE_AUDIT_LOG moves or disables it). GENOFFICE_USER_DATA points genoffice at a non-default GenOffice profile (open-documents registry, AI settings).
• Image ops (addPicture, setImageFill, addMedia) accept a local file path in their bytes field; genoffice reads it.

Limits

• Conversions to PDF run inside the GenOffice app (hidden, a few seconds each); they need GenOffice installed, or GENOFFICE_APP_BIN pointing at it; the same holds for docx→html and html→docx.
• add_pivot writes the pivot's cells at targetCell (no values or formulas there, on a sheet that already exists in the file) plus a native pivot Excel refreshes, source formulas are evaluated from the file so set them in an earlier batch; add_sparkline writes one in-cell sparkline per data row (at most 200 rows per op); convert_to_values replaces formulas with the values the workbook engine computes from the file (error results keep their formula; cell edits go in an earlier batch); set_page_setup also takes printTitles, header/footer and rowBreaks/colBreaks. Excel ops that still need the live editor (refresh_pivot, edits to session-created tables and shapes) are refused with the reason. add_conditional_format and set_data_validation add to the rules a sheet already has (set_data_validation on a range that has one replaces it, null removes it); clear_conditional_formats starts over.
• Formulas are evaluated with the workbook engine after writing, so sheet read and cached-value readers see numbers.