> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# office

> Supported OfficeCLI commands for Excel workbooks, Word documents and PowerPoint decks.

Create, read and edit `.xlsx` workbooks, and read `.docx` documents and
`.pptx` decks, on any mount. Mirage implements the commands below with
[OfficeCLI](https://github.com/iOfficeAI/OfficeCLI)'s paths, output and
messages.

## Setup

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

```python theme={null}
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](https://docs.mirage.strukto.ai/python/cli/index.md#register-a-cli).

## 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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.