---
name: officecli
description: Use OfficeCLI to create, inspect, validate, and modify Office documents (.docx, .xlsx, .pptx) from the terminal. Use when the user wants Office document automation, extraction, validation, or editing.
---

# OfficeCLI

OfficeCLI is bundled into Docyrus pi sessions as a local command-line tool for Word, Excel, and PowerPoint files.
The Docyrus package provisions the binary for the current platform, and OfficeCLI update checks are disabled because Docyrus releases manage binary updates.

Use the CLI directly in this environment. Do not run `officecli mcp ...` unless the user explicitly asks to register OfficeCLI with another editor or agent.

## First Principles

- Prefer structured output by adding `--json` whenever you need to inspect or transform results.
- Work from higher-level commands down:
  - L1 read and inspection: `view`, `get`, `query`, `validate`
  - L2 DOM edits: `set`, `add`, `remove`, `move`, `batch`
  - L3 raw XML fallback: `raw`, `raw-set`, `add-part`
- When unsure about element names, property names, or allowed value formats, run help instead of guessing.
- After making changes, run `officecli validate <file>` and, when useful, `officecli view <file> issues`.
- For multi-step edits on a single file, use `open` and `close` to keep the document in memory.

## Verify Availability

```bash
officecli --version
officecli --help
```

If a command fails unexpectedly, inspect the help for the specific document type before trying alternatives.

## Help-First Workflow

```bash
officecli docx set
officecli docx set paragraph
officecli xlsx set cell.value
officecli pptx add chart
officecli pptx query
```

Use the deepest help entry you already know. One help lookup is better than guessing and retrying.

## Common Commands

Create a new document:

```bash
officecli create report.docx
officecli create model.xlsx
officecli create deck.pptx
```

Inspect document structure or extracted text:

```bash
officecli view report.docx outline
officecli view report.docx text --max-lines 80
officecli view deck.pptx issues
officecli get deck.pptx /slide[1] --depth 1 --json
officecli query model.xlsx 'cell[value~=Revenue]' --json
```

Modify content:

```bash
officecli set report.docx /body/p[1] --prop style=Heading1 --prop text="Executive Summary"
officecli add deck.pptx / --type slide --prop title="Q4 Report"
officecli add deck.pptx /slide[1] --type shape --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm
officecli set model.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
```

Batch related changes:

```bash
echo '[{"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":"true"}},{"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":"true"}}]' | officecli batch model.xlsx --json
```

Keep a document open for a longer edit session:

```bash
officecli open report.docx
officecli set report.docx /body/p[2] --prop text="Updated paragraph"
officecli close report.docx
```

## Practical Guidance

- Prefer `view`, `get`, or `query` to understand the document before editing it.
- Use `query` to locate matching elements instead of hard-coding guessed paths.
- Keep outputs bounded for large files with flags such as `--max-lines`, `--start`, or `--end`.
- Path indexing is 1-based: `/body/p[3]` means the third paragraph.
- Use `batch` when several changes should be applied in one save cycle.
- Use `watch` for PowerPoint only when the user explicitly wants a live preview flow.

## When Raw XML Is Appropriate

Only fall back to `raw` or `raw-set` when:

- the higher-level commands cannot express the change,
- you already inspected the target part with `get` or `raw`,
- and you are prepared to validate immediately afterwards.

## Validation Checklist

After editing:

```bash
officecli validate <file>
officecli view <file> issues
```

If validation fails, fix the issue before presenting the result as complete.
