office

Create, read and edit .xlsx workbooks, and read .docx documents and .pptx decks, on any mount. Mirage implements the commands below with OfficeCLI’s paths, output and messages.

Setup

office has no account config. It reads and writes workbooks through existing mounts.

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.office import OFFICE
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/data/": RAMVFS()}, mode=MountMode.WRITE)
ws.register_cli("office", OFFICE)

For YAML registration, see the CLI overview.

Supported commands

Run office <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Command	Description
`office create`	Create a blank Office document
`office get`	Get a document node by path
`office query`	Query document elements with CSS-like selectors
`office set`	Modify a document node’s properties
`office remove`	Remove an element from the document
`office batch`	Execute multiple commands from a JSON array in a single pass

Edit a workbook

office create /data/report.xlsx
office set /data/report.xlsx /Sheet1/A1 --prop value=Revenue
office set /data/report.xlsx /Sheet1/B1 --prop value=1250.5
office set /data/report.xlsx Sheet1!C1 --prop value=2024-03-15
office get /data/report.xlsx /Sheet1
office get /data/report.xlsx /Sheet1/A1 --json

A path names the workbook (/), a sheet (/Sheet1), a cell (/Sheet1/A1 or Sheet1!A1), a range (/Sheet1/A1:C9), a row (/Sheet1/row[2]) or a comment by its place on the sheet (/Sheet1/comment[1]). get shows each cell’s value, type, font, fill, border, alignment, protection and number format, and the workbook’s and each sheet’s own properties.

Command	Props
`set` on a cell	`value`, `type` (`string` or `number`), `formula`
`set` on a sheet	`hidden`
`remove`	a comment

Batch

office create /data/sales.xlsx
office batch /data/sales.xlsx --commands '[
  {"command":"set","path":"/Sheet1/A1","props":{"value":"Region"}},
  {"command":"set","path":"/Sheet1/B1","props":{"value":"Revenue"}},
  {"command":"set","path":"/Sheet1/A2","props":{"value":"North"}},
  {"command":"set","path":"/Sheet1/B2","props":{"value":"1250.5"}},
  {"command":"set","path":"/Sheet1/A3","props":{"value":"South"}},
  {"command":"set","path":"/Sheet1/B3","props":{"value":"830"}}
]'

The items run against one open workbook, saved once. A failure anywhere leaves the workbook as it was, unless --best-effort keeps what succeeded; --stop-on-error stops at the first failure. The JSON also comes from --input FILE or stdin.

Query

office query /data/sales.xlsx 'row[Revenue>1000]'
office query /data/sales.xlsx 'B[value>500]'
office query /data/sales.xlsx 'Sheet1!cell:contains(South)'
office query /data/sales.xlsx 'cell[type=Number], comment' --json

A selector names cells (cell or a column letter such as B), rows, comments or sheets, scoped to one sheet with Sheet1! or /Sheet1/. Predicates in brackets compare a property with =, !=, ~=, >, <, >= or <= and join with and, or and not(...); :contains(text), :empty and :has(formula) filter cells, [N] picks a row or comment, , joins selectors and > picks children. A row predicate on a column name reads the sheet’s table, defined or found from its header row.

Read a document or deck

office get /data/memo.docx /body --depth 2
office get /data/memo.docx /body/p[1]/r[1] --json
office query /data/memo.docx 'p[style=Heading1]'
office get /data/deck.pptx /slide[1] --depth 3
office query /data/deck.pptx 'shape:contains(Revenue)'

A Word path names the body (/body), a paragraph (/body/p[2] or /body/p[@paraId=1A2B3C4D]), its runs, a table, row or cell (/body/tbl[1]/tr[1]/tc[2]), a section (/section[1]), a style (/styles/Heading1), a header or a footer (/header[1]). A PowerPoint path names a slide (/slide[1]), a shape (/slide[1]/shape[@id=2]), its paragraphs and runs, a table, picture, chart, group, connector or placeholder (/slide[1]/placeholder[title]), a layout or a master. get shows each node’s own properties and what it inherits, as effective.* keys with the layer each came from in .src. A query selector names an element such as paragraph, run, table, cell, picture, style, slide or shape, with the same predicates, :contains(text) and :empty.

Differences from OfficeCLI

create, set and remove take .xlsx workbooks only; .docx and .pptx files take get, query and batch items that read.
An equation’s text is plain, not LaTeX, and a chart in a deck shows its frame and name but not its plot properties.
A Word query reads paragraphs, runs, tables, rows, cells, pictures, hyperlinks, bookmarks, equations, content controls, sections, headers, footers and styles. A PowerPoint query returns no comments, OLE objects, zooms, 3D models or animations.
A document part that is not well-formed XML reads as absent, where OfficeCLI refuses the file.
A formula is stored without a computed value, and Excel calculates it on open. A formula cell with no stored value shows #OCLI_NOTEVAL! and evaluated=false.
create writes a blank workbook with no document properties or theme.
set takes the props above; overwriting the first cell of a shared formula is refused.
query reads cells, rows, comments and sheets; charts, tables, pivot tables and other elements return no matches.
batch runs get, query, set and remove items.
Usage errors and --help use Mirage’s wording. Messages that name the command say office.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes