---
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 available in Docyrus pi sessions as a local command-line tool for Word, Excel, and PowerPoint files.

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.
