# Command Examples for Manipulating Excel Documents with OfficeCLI

> Master Excel manipulation with OfficeCLI. Explore command examples for create, set, add, query, and batch operations. Programmatically manage XLSX files with ease.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-18

---

**OfficeCLI provides a resident server architecture that dispatches Excel commands through [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), enabling programmatic manipulation of XLSX files via verbs like `create`, `set`, `add`, `query`, and `batch`.**

OfficeCLI is a single-binary, cross-platform command-line tool developed by iOfficeAI that exposes Excel document manipulation through a resident server model. Understanding the available command examples for manipulating Excel documents with OfficeCLI allows developers to automate workbook generation, apply formatting, import datasets, and validate outputs without opening a GUI. The CLI delegates all XLSX-specific operations to [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs) while command routing is managed by [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs), with the authoritative schema documented in [`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md).

## Command Architecture and Dispatch

When you execute an OfficeCLI command, the binary communicates with a resident server defined in [[`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs)](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs). The server parses the verb—such as `create`, `open`, `set`, `add`, `query`, `view`, or `batch`—and dispatches the operation to the appropriate handler based on file extension. For Excel documents, this routing targets [[`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs)](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/ExcelHandler.cs), which implements the actual OOXML manipulation logic.

The **XLSX skill specification** in [[`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md)](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md) serves as the canonical reference for all supported properties and element types, ensuring that the CLI commands you construct align with the internal object model.

## Creating and Opening Workbooks

All Excel sessions begin with creating a file or opening an existing document in the resident server. The `create` verb generates a new OOXML package, while `open` loads an existing workbook into memory for subsequent operations.

```bash
officecli create "budget.xlsx"
officecli open "budget.xlsx"

```

## Writing Data and Formulas

The `set` verb manipulates cell values, formulas, and basic formatting. You specify the target using a path notation (`/Sheet1/A1`) and pass properties via `--prop` flags.

### Static Values and Formatting

```bash
officecli set "budget.xlsx" "/Sheet1/A1" --prop value=Month --prop bold=true
officecli set "budget.xlsx" "/Sheet1/B1" --prop value=Revenue --prop bold=true
officecli set "budget.xlsx" "/Sheet1/B2" --prop value=42000 --prop numFmt='$#,##0'

```

### Formula Insertion

Formulas are cached automatically by the resident server. Use the `formula` property and include standard Excel syntax.

```bash
officecli set "budget.xlsx" "/Sheet1/B5" \
    --prop formula="SUM(B2:B4)" \
    --prop bold=true \
    --prop numFmt='$#,##0'

```

## Formatting and Layout

To prevent display truncation (indicated by `###` characters), adjust column widths explicitly using the `set` command on column identifiers.

```bash
officecli set "budget.xlsx" "/Sheet1/col[A]" --prop width=12
officecli set "budget.xlsx" "/Sheet1/col[B]" --prop width=15

```

## Importing Bulk Data

For large datasets, the `import` verb reads CSV files and populates sheets directly, bypassing the overhead of individual `set` calls. The `--header` flag treats the first row as column headers.

```bash
officecli import "budget.xlsx" /Sheet1 --file sales.csv --header

```

## Advanced Structures: Tables, Charts, and Named Ranges

The `add` verb creates complex OOXML elements such as tables (ListObjects), charts, and named ranges.

### Adding a Table

Tables enable auto-filtering and structured references in formulas.

```bash
officecli add "budget.xlsx" /Sheet1 \
    --type table \
    --prop range="A1:B5" \
    --prop name=RevenueTable

```

### Creating a Named Range

Named ranges simplify formula maintenance and can be defined via batch commands for complex scenarios.

```bash
cat <<'EOF' | officecli batch "budget.xlsx"
[
  {"command":"add","parent":"/","type":"namedrange","props":{"name":"GrowthRate","ref":"Sheet1!$B$6"}}
]
EOF

```

### Inserting Charts

Charts reference data ranges and render as embedded drawings in the worksheet.

```bash
officecli add "budget.xlsx" /Sheet1 \
    --type chart \
    --prop chartType=column \
    --prop dataRange="Sheet1!A2:B5" \
    --prop title="Monthly Revenue"

```

## Querying and Validation

The `query` verb searches for specific cell conditions, such as error values or formula presence, enabling automated QA workflows.

```bash
officecli query "budget.xlsx" 'cell:contains("#REF!")'
officecli query "budget.xlsx" 'cell:has(formula)'

```

To verify visual layout without opening Excel, generate an HTML preview that reveals truncation, overflow, or placeholder artifacts.

```bash
officecli view "budget.xlsx" html

```

## Batch Operations and Session Management

Complex multi-step modifications can be bundled into JSON and sent as a single `batch` command, reducing round-trip latency to the resident server. Always close the session to flush changes and `validate` to force a write and schema check.

```bash
officecli close "budget.xlsx"
officecli validate "budget.xlsx"

```

## Summary

- **OfficeCLI** uses a resident server model where [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) routes commands and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs) executes Excel-specific logic.
- Core verbs include **`create`**, **`open`**, **`set`**, **`add`**, **`import`**, **`query`**, **`view`**, **`batch`**, **`close`**, and **`validate`**.
- Use **`set`** for cell values, formulas, and column widths; use **`add`** for tables, charts, and named ranges.
- Bulk data insertion prefers the **`import`** verb with CSV files over iterative `set` calls.
- The canonical schema reference lives in **[`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md)**, ensuring property names match the internal OOXML model.
- Always adjust column widths and close sessions to persist changes, validating the final package for structural integrity.

## Frequently Asked Questions

### How does OfficeCLI route Excel commands to the appropriate handler?

OfficeCLI maintains a resident server implemented in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) that listens for CLI input. When a command targets an `.xlsx` file, the server inspects the file extension and dispatches the operation to [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), which contains the full implementation for spreadsheet manipulation as defined in the source around lines 523-527.

### What is the difference between `set` and `add` commands in OfficeCLI?

The **`set`** command modifies existing elements—such as writing a value to a cell or adjusting a column width—while the **`add`** command creates new structural elements like tables, charts, or named ranges that did not previously exist in the workbook. Use `set` for updates and `add` for instantiation.

### How can I validate an Excel file after modifications?

After closing the resident session with `officecli close "file.xlsx"`, run `officecli validate "file.xlsx"` to force a write to disk and perform structural validation against the OOXML schema. This step catches errors such as broken references or malformed formulas before distribution.

### Where can I find the complete schema reference for Excel properties?

The complete schema, including all valid property names for cells, rows, columns, charts, and tables, is documented in [`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md) within the repository. This file serves as the source of truth for the CLI's help system and should be consulted when constructing complex `--prop` arguments.