Command Examples for Manipulating Excel Documents with OfficeCLI

OfficeCLI provides a resident server architecture that dispatches Excel commands through 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 while command routing is managed by McpServer.cs, with the authoritative schema documented in 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/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/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) 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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

officecli close "budget.xlsx"
officecli validate "budget.xlsx"

Summary

• OfficeCLI uses a resident server model where McpServer.cs routes commands and 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, 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}