> ## 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 CLI in Python

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

Create, read and edit `.xlsx` workbooks, `.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 files 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).

## SKILL.md

The [SKILL.md](https://docs.mirage.strukto.ai/home/setup/cli/skill-md.md) an agent reads with `office` installed.

> [tab] Rendered
>
> **Available commands**
>
> These commands are registered with this shell; `--help` after a command or subcommand shows its usage.
>
> **`office`**
>
> ```text theme={null}
> usage: office [-h] {create,get,query,set,add,remove,move,swap,batch} ...
>
> office: AI-friendly CLI for Office documents (.docx, .xlsx, .pptx)
>
> commands:
>   create  Create a blank Office document
>   get     Get a document node by path
>   query   Query document elements with CSS-like selectors
>   set     Modify a document node's properties
>   add     Add a new element to the document
>   remove  Remove an element from the document
>   move    Move an element to a new position or parent
>   swap    Swap two elements in the document
>   batch   Execute multiple commands from a JSON array in a single pass
>
> options:
>   -h, --help  Show this help and exit
> ```

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-commands
> description: The CLIs registered in this workspace and how to call them.
> ---
>
> # Available commands
>
> These commands are registered with this shell; `--help` after a command or subcommand shows its usage.
>
> ## `office`
>
> ```text
> usage: office [-h] {create,get,query,set,add,remove,move,swap,batch} ...
>
> office: AI-friendly CLI for Office documents (.docx, .xlsx, .pptx)
>
> commands:
>   create  Create a blank Office document
>   get     Get a document node by path
>   query   Query document elements with CSS-like selectors
>   set     Modify a document node's properties
>   add     Add a new element to the document
>   remove  Remove an element from the document
>   move    Move an element to a new position or parent
>   swap    Swap two elements in the document
>   batch   Execute multiple commands from a JSON array in a single pass
>
> options:
>   -h, --help  Show this help and exit
> ```
> ````

## 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 add` | Add a new element to the document |
| `office remove` | Remove an element from the document |
| `office move` | Move an element to a new position or parent |
| `office swap` | Swap two elements in the document |
| `office batch` | Execute multiple commands from a JSON array in a single pass |

## Usage

### 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 | `name`, `hidden` |
| `add --type sheet` | `name`, `position`, `hidden`, `tabColor` |
| `remove` | a sheet or a comment |

Renaming a sheet renames it in every formula, defined name, link and chart
that points at it.

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

### Edit a document

```bash theme={null}
office create /data/memo.docx
office add /data/memo.docx /body --type paragraph --prop text="Quarterly review" --prop style=Heading1
office add /data/memo.docx /body --type paragraph --prop text="Revenue grew." --prop bold=true
office add /data/memo.docx /body --type paragraph --prop text="North led" --prop listStyle=bullet
office add /data/memo.docx '/body/p[2]' --type hyperlink --prop url=https://example.com --prop text=details
office add /data/memo.docx /body --type table --prop data="Region,Revenue;North,1250"
office add /data/memo.docx '/body/tbl[1]' --type row --prop c1=South --prop c2=830
office add /data/memo.docx /body --type picture --prop src=/data/chart.png --prop width=12cm --prop alt="Revenue by region"
office set /data/memo.docx '/body/tbl[1]/tr[1]/tc[1]' --prop shading=FFC000
office move /data/memo.docx '/body/p[2]' --index 0
office swap /data/memo.docx '/body/p[1]' '/body/p[2]'
office remove /data/memo.docx '/body/p[2]'
```

`add` makes a paragraph, a run or a hyperlink in a paragraph, a table, a
row, a cell, a picture or a page, column or line break (`pagebreak`,
`columnbreak`, `break`). A
paragraph takes `text` (each `\n` starts another paragraph), `style`,
`alignment`, spacing and indents, and the run props `bold`, `italic`,
`underline`, `size`, `font`, `color`, `highlight` and the other toggles. A
table takes `rows` and `cols`, or `data` with `;` between rows and `,`
between cells; a row takes its cells' text as `c1`, `c2` and so on, and
`height` and `header`; a cell takes `text`, `width`, `shading` and
`gridSpan`. `set` changes the same props on a paragraph or run,
and `text` and `shading` on a cell. A built-in style such as `Heading1`
that the document lacks is added with Word's definition. `listStyle`
(`bullet`, `numbered` or `none`) with `listLevel` and `start` puts a
paragraph in a list, continuing the list just before it when that one is
the same kind. A hyperlink takes `url` or `anchor`, `text` and the run
props. A picture takes `src`, a file or a base64 `data:` URI, with `width`
and `height`; a side left out follows the image's aspect, 6 inches wide by
default. It also takes `alt`, `name` and `crop`, and `wrap` (`square`,
`tight`, `through` or `topandbottom`) with `hposition`, `vposition`,
`hrelative` and `vrelative` to float it. In a paragraph it is appended as a
run; anywhere else it gets a paragraph of its own.

### Edit a deck

```bash theme={null}
office create /data/deck.pptx
office add /data/deck.pptx / --type slide --prop layout=title --prop title=Results
office add /data/deck.pptx '/slide[1]' --type textbox --prop text="Up 12%" --prop x=2cm --prop y=12cm --prop size=24
office add /data/deck.pptx '/slide[1]' --type table --prop data="Q1,Q2;10,12"
office set /data/deck.pptx '/slide[1]/shape[2]' --prop fill=FFC000 --prop bold=true
office set /data/deck.pptx '/slide[1]/table[1]/tr[1]/tc[1]' --prop text=Quarter --prop bold=true
office add /data/deck.pptx '/slide[1]/table[1]' --type row
office add /data/deck.pptx '/slide[1]' --type picture --prop src=/data/logo.png --prop width=4cm --prop x=1cm --prop y=1cm
office add /data/deck.pptx '/slide[1]' --type notes --prop text="Mention the Q2 launch"
office add /data/deck.pptx / --type slide --prop layout="Title and Content" --prop title=Next --prop text="One\nTwo"
office move /data/deck.pptx '/slide[2]' --index 0
office remove /data/deck.pptx '/slide[2]'
```

`add` makes a slide from a layout, chosen by name, type or number, with its
`title` and `text`; a text box with `text`, `x`, `y`, `width`, `height`,
`fill` and the run props `size`, `bold`, `italic`, `underline`, `color` and
`font`; a table of `rows` and `cols`, or `data`, and rows in it; a picture
from `src` with `x`, `y`, `width`, `height`, `alt`, `name`, `crop`,
`rotation`, `flipH`, `flipV` and `opacity`, centered and 6 inches wide at
the image's aspect unless placed; or a slide's speaker notes with `text`. `set` changes the same props on a shape,
`text`, the run props, `fill` and `alignment` on a table cell
(`/slide[N]/table[K]/tr[R]/tc[C]`), `text` on `/slide[N]/notes`, and
`hidden` and `notes` on a slide. A shape placed or moved prints its
position, and a warning when another shape starts at the same spot.
`move` and `swap` reorder slides, or the shapes of one slide.

## Behavior

### Differences from OfficeCLI

* `add` makes the element types above; others, such as charts, comments and
  headers, and `add --from` are not available yet. `set` takes the props
  above.
* A picture's `src` is a file or a `data:` URI; a URL is not fetched.
* Renaming a sheet changes only whole references to it, so `OtherData!A1`
  stays when `Data` is renamed. Removing the last visible sheet is refused,
  and a list item added with `--index`, `--after` or `--before` continues
  the list just before it.
* 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`.
* `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`, `add`, `remove`, `move` and `swap`
  items.
* A save does not stamp the `OfficeCLI.LastModified` custom property.
* Usage errors and `--help` use Mirage's wording. Messages that name the command
  say `office`.

## License

| Project | Role in Mirage | License |
| - | - | - |
| [OfficeCLI](https://github.com/iOfficeAI/OfficeCLI) 1.0.161 | Upstream CLI; its paths, properties, output and messages are adapted | [Apache-2.0](https://github.com/strukto-ai/mirage/blob/main/licenses/third_party/officecli.txt) |
| [Mirage](https://github.com/strukto-ai/mirage) | Command implementation | [Apache-2.0](https://github.com/strukto-ai/mirage/blob/main/LICENSE) |

See [compatibility and licenses](https://docs.mirage.strukto.ai/home/setup/clis.md#compatibility-and-licenses).


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