Xlsx

---
name: xlsx
description: Create and edit Excel .xlsx workbooks (sheets, cells, formulas, formatting) via Python `openpyxl`. Use to generate spreadsheets or write/update cells. Reading is via os.fs.read_document.
version: 1.0.1
requires_tools:
  - os.shell.run
  - os.fs.read_document
dangerous: false
platforms:
  - darwin
  - linux
---

# xlsx

Create and modify `.xlsx` workbooks with the `openpyxl` Python library.
**Reading** an existing spreadsheet to plain text is best done with the built-in
`os.fs.read_document` tool (no install). Use the scripts below to **write**:
new workbooks, cell values, formulas, and basic formatting.

The pattern is `python3 -c "<inline script>"` (or `python3 script.py` for longer
logic). Keep scripts short and idempotent; always write to a fresh output path.

## Setup health check (run first, every session)

Verify with **one solo step**:

```
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; print(openpyxl.__version__)"] } }]
```

Outcome map:
- `exit 0` + version → ready, proceed.
- `ModuleNotFoundError: openpyxl` → enter **Setup playbook → "openpyxl missing"**.
- `command not found: python3` → reply that Python 3 is required and stop.

## Setup playbook (when prerequisites are missing)

### openpyxl missing

Reply (solo `reply` step):

> "The `openpyxl` library is not installed. I can install it: `python3 -m pip install --user openpyxl`. Install it?"

On yes:

```
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-m", "pip", "install", "--user", "openpyxl"] } }]
```

If `pip` is externally managed (PEP 668), use `pipx run --spec openpyxl python` or
a venv; ask the user which they prefer.

## When to use

- "Create an Excel file with these rows", "build a budget spreadsheet".
- "Add a column / formula", "update cell B2", "add a second sheet".
- Generating reports/exports as `.xlsx`.

## When NOT to use

- Reading an `.xlsx` to summarise — use `os.fs.read_document`.
- CSV-only work — prefer plain `os.fs.write` with comma-separated text.
- Charts / pivot tables / macros — out of scope on v1.

## Common operations

Create a workbook with a header row and two data rows:

```
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; wb=openpyxl.Workbook(); ws=wb.active; ws.title='Report'; ws.append(['Name','Amount']); ws.append(['Coffee',4.5]); ws.append(['Tea',3]); ws['B4']='=SUM(B2:B3)'; wb.save('report.xlsx'); print('wrote report.xlsx')"] } }]
```

Append rows to an existing workbook:

```
[{ "tool": "os.shell.run", "args": { "cmd": "python3", "args": ["-c", "import openpyxl; wb=openpyxl.load_workbook('report.xlsx'); ws=wb.active; ws.append(['Juice',5]); wb.save('report.xlsx'); print('appended')"] } }]
```

For anything longer than a couple of statements, write a `.py` file with
`os.fs.write` first, then run it with `python3 script.py`.

## Rules

1. Always `wb.save(<new path>)` and report the path; never silently overwrite.
2. Formulas go in as strings starting with `=` (e.g. `'=SUM(A1:A9)'`).
3. Quote numbers as numbers, not strings, so Excel treats them numerically.
4. For reads, defer to `os.fs.read_document` — do not reinvent parsing.