excel-cli | SkillBundle

Excel Automation with excelcli

Preconditions

Windows host with Microsoft Excel installed (2016+)
Uses COM interop — does NOT work on macOS or Linux
Every command below invokes excelcli directly, so it must resolve on PATH. Installing the excel-cli plugin does not put it there — the global shim is opt-in. Run com.github.copilot\bin\install-global.ps1 from the installed plugin folder once (it writes excelcli.cmd / excelcli.ps1 into ~\.copilot\bin and adds that to your user PATH), or install the runtime independently via the standalone release zip or dotnet tool install --global Sbroenne.ExcelMcp.CLI. If excelcli is not found, report that and stop — do not guess at a path.
In an Agent Plugins host, the runtime is downloaded and cached under PLUGIN_DATA\runtime; release freshness is checked once per Copilot session. The optional global shim falls back to ~\.copilot\plugin-runtime\mcp-server-excel\excel-cli and checks for updates at most once every 24 hours.

Workflow Checklist

Step	Command	When
1. Session	`session create/open`	Always first
2. Sheets	`sheet create/rename`	If needed
3. Write data	See below	If writing values
4. Save & close	`session close --save`	Always last

10+ commands? Use excelcli -q batch --input commands.json — sends all commands in one process with automatic session management. See Rule 8.

Writing Data (Step 3):

--values takes a JSON 2D array string: --values '[["Header1","Header2"],[1,2]]'
Write one row at a time for reliability: --range A1:B1 --values '[["Name","Age"]]'
Strings MUST be double-quoted in JSON: "text". Numbers are bare: 42
Always wrap the entire JSON value in single quotes to protect special characters

CRITICAL RULES (MUST FOLLOW)

⚡ Building dashboards or bulk operations? Skip to Rule 8: Batch Mode — it eliminates per-command process overhead and auto-manages session IDs.

Rule 1: NEVER Ask Clarifying Questions

Execute commands to discover the answer instead:

DON'T ASK	DO THIS INSTEAD
"Which file should I use?"	`excelcli -q session list`
"What table should I use?"	`excelcli -q table list --session <id>`
"Which sheet has the data?"	`excelcli -q sheet list --session <id>`

You have commands to answer your own questions. USE THEM.

Rule 2: Always End With a Text Summary

NEVER end your turn with only a command execution. After completing all operations, always provide a brief text message confirming what was done. Silent command-only responses are incomplete.

Rule 3: Session Lifecycle

Creating vs Opening Files:

# NEW file - use session create
excelcli -q session create C:\path\newfile.xlsx  # Creates file + returns session ID
 
# EXISTING file - use session open
excelcli -q session open C:\path\existing.xlsx   # Opens file + returns session ID

CRITICAL: Use session create for new files. session open on non-existent files will fail!

CRITICAL: ALWAYS use the session ID returned by session create or session open in subsequent commands. NEVER guess or hardcode session IDs. The session ID is in the JSON output (e.g., {"sessionId":"abc123"}). Parse it and use it.

Unclosed sessions leave Excel processes running, locking files.

Rule 4: Data Model Prerequisites

DAX operations require tables in the Data Model:

Rule 5: Power Query Development Lifecycle

BEST PRACTICE: Test M code before creating permanent queries

Rule 6: Report File Errors Immediately

If you see "File not found" or "Path not found" - STOP and report to user. Don't retry.

Rule 7: Use Calculation Mode for Bulk Writes

When writing many values/formulas (10+ cells), disable auto-recalc for performance:

Rule 8: Use Batch Mode for Bulk Operations (10+ commands)

When executing 10+ commands on the same file, use excelcli batch to send all commands in a single process launch. This avoids per-process startup overhead and terminal buffer saturation.

Key features:

Session auto-capture: session.open/create result sessionId auto-injected into subsequent commands — no need to parse and pass session IDs
NDJSON output: One JSON result per line: {"index": 0, "command": "...", "success": true, "result": {...}}
--stop-on-error: Exit on first failure (default: continue all)
--session <id>: Pre-set session ID for all commands (skip session.open)

Input formats:

JSON array from file: excelcli -q batch --input commands.json
NDJSON from stdin: Get-Content commands.ndjson | excelcli -q batch

CLI Command Reference

Full reference: See CLI command reference and common pitfalls, or run excelcli <command> --help for live help from the installed runtime.

Syntax rule: CLI commands use excelcli -q <command> <action> --session <id> --kebab-case-flags .... Do not use MCP call syntax such as range(action: ...), snake_case parameters, or underscore tool names. The CLI command names remove MCP underscores: calculation_mode becomes calculationmode, range_format becomes rangeformat, chart_config becomes chartconfig, and data_model becomes datamodel.

Available command groups:

session, batch, service, analysis, calculationmode, chart, chartconfig, conditionalformat, connection, datamodel, datamodelrelationship, drawing, namedrange, pivottable, pivottablecalc, pivottablefield, powerquery, pythoninexcel, querytable, range, rangeedit, rangeformat, rangelink, screenshot, sheet, worksheetstyle, slicer, table, tablecolumn, vba, window, workbook, xmlmap

Common Pitfalls

See CLI command reference and common pitfalls for examples. Key issues:

--values-file expects a path to an existing file; use --values for inline JSON.
--timeout ranges are action-specific: session open/create accepts 10-3600; Power Query refresh/refresh-all accepts 0-2147483 (0 keeps the default); other generated timeout actions accept 1-2147483.
--values takes a 2D JSON array such as '[["Name","Age"],["Alice",30]]'.
List parameters such as --selected-items require JSON arrays.
Power Query operations can take 30+ seconds; use a deliberate data-operation timeout or 0 for the default.

Reference Documentation