Sbroenne.ExcelMcp.CLI 1.6.9

ExcelMcp.CLI - Command-Line Interface for Excel Automation

Command-line interface for Excel automation — preferred by coding agents.

The CLI provides 14 command categories with 211 operations matching the MCP Server. Uses 64% fewer tokens than MCP Server because it wraps all operations in a single tool with skill-based guidance instead of loading 22 tool schemas into context.

Also perfect for RPA workflows, CI/CD pipelines, batch processing, and automated testing.

➡️ Learn more and see examples

🚀 Quick Start

Installation (.NET Global Tool - Recommended)

# Install globally (requires .NET 10 SDK)
dotnet tool install --global Sbroenne.ExcelMcp.CLI

# Verify installation
excelcli --version

# Get help
excelcli --help

🔁 Session Workflow: Always start with excelcli session open <file> (captures the session id), pass --session <id> to other commands, then excelcli session close <id> --save when finished. The CLI reuses the same Excel instance through that lifecycle.

Check for Updates

# Check if newer version is available
excelcli version --check

# Update if available
dotnet tool update --global Sbroenne.ExcelMcp.CLI

Uninstall

dotnet tool uninstall --global Sbroenne.ExcelMcp.CLI

🤫 Quiet Mode (Agent-Friendly)

For scripting and coding agents, use -q/--quiet to suppress banner and output JSON only:

excelcli -q session open data.xlsx
excelcli -q range get-values --session 1 --sheet Sheet1 --range A1:B2
excelcli -q session close --session 1 --save

Banner auto-suppresses when stdout is piped or redirected.

🆘 Built-in Help

• excelcli --help – lists every command category plus the new descriptions from Program.cs
• excelcli <command> --help – shows verb-specific arguments (for example excelcli sheet --help)
• excelcli session --help – displays nested verbs such as open, save, close, and list

Descriptions are kept in sync with the CLI source so the help output always reflects the latest capabilities.

✨ Key Features

🔧 Excel Development Automation

• Power Query Management - Export, import, update, and version control M code
• VBA Development - Manage VBA modules, run macros, automated testing
• Data Model & DAX - Create measures, manage relationships, Power Pivot operations
• PivotTable Automation - Create, configure, and manage PivotTables programmatically
• Conditional Formatting - Add rules (cell value, expression-based), clear formatting

📊 Data Operations

• Worksheet Management - Create, rename, copy, delete sheets with tab colors and visibility
• Range Operations - Read/write values, formulas, formatting, validation
• Excel Tables - Lifecycle management, filtering, sorting, structured references
• Connection Management - OLEDB, ODBC, Text, Web connections with testing

🛡️ Production Ready

• Zero Corruption Risk - Uses Excel's native COM API (not file manipulation)
• Error Handling - Comprehensive validation and helpful error messages
• CI/CD Integration - Perfect for automated workflows and testing
• Windows Native - Optimized for Windows Excel automation

📋 Command Categories

ExcelMcp.CLI provides 211 operations across 14 command categories:

📚 Complete Feature Reference → - Full documentation with all operations

Quick Reference:

Note: CLI uses session commands for multi-operation workflows.

SESSION LIFECYCLE (Open/Save/Close)

The CLI uses an explicit session-based workflow where you open a file, perform operations, and optionally save before closing:

# 1. Open a session
excelcli session open data.xlsx
# Output: Session ID: 550e8400-e29b-41d4-a716-446655440000

# 2. List active sessions anytime
excelcli session list

# 3. Use the session ID with any commands
excelcli sheet create --session 550e8400-e29b-41d4-a716-446655440000 --sheet "NewSheet"
excelcli powerquery list --session 550e8400-e29b-41d4-a716-446655440000

# 4. Close and save changes
excelcli session close 550e8400-e29b-41d4-a716-446655440000 --save

# OR: Close and discard changes (no --save flag)
excelcli session close 550e8400-e29b-41d4-a716-446655440000

Session Lifecycle Benefits

• Explicit control - Know exactly when changes are persisted with --save
• Batch efficiency - Keep single Excel instance open for multiple operations (75-90% faster)
• Flexibility - Save and close in one command, or close without saving
• Clean resource management - Automatic Excel cleanup when session closes

Background Daemon & System Tray

When you run your first CLI command, a background daemon starts automatically. The daemon:

• Manages Excel COM - Keeps Excel instance alive between commands (no restart overhead)
• Shows system tray icon - Look for the Excel CLI icon in your Windows taskbar notification area
• Tracks sessions - Right-click the tray icon to see active sessions and close them
• Auto-updates - Notifies you when a new version is available and allows one-click updates

Tray Icon Features:

• 📋 View sessions - Double-click to see active session count
• 💾 Close sessions - Right-click → Sessions → select file → "Close Session..." (prompts to save with Cancel option)
• 🔄 Update CLI - When updates are available, click "Update to X.X.X" to update automatically
• 🛑 Stop daemon - Right-click → "Stop Daemon" (prompts to save active sessions with Cancel option)

The daemon auto-stops after 10 minutes of inactivity (no active sessions).

💡 Command Reference

Use excelcli <command> --help for complete parameter documentation. The CLI help is always in sync with the code.

excelcli --help              # List all commands
excelcli session --help      # Session lifecycle (open, close, save, list)
excelcli powerquery --help   # Power Query operations
excelcli range --help        # Cell/range operations
excelcli table --help        # Excel Table operations
excelcli pivottable --help   # PivotTable operations
excelcli datamodel --help    # Data Model & DAX
excelcli vba --help          # VBA module management

Typical Workflows

Session-based automation (recommended):

excelcli -q session open report.xlsx           # Returns session ID
excelcli -q sheet create --session 1 --sheet "Summary"
excelcli -q range set-values --session 1 --sheet Summary --range A1 --values '[["Hello"]]'
excelcli -q session close --session 1 --save   # Persist changes

Power Query ETL:

excelcli powerquery create --session 1 --query "CleanData" --mcode-file transform.pq
excelcli powerquery refresh --session 1 --query "CleanData"

PivotTable from Data Model:

excelcli pivottable create-from-datamodel --session 1 --table Sales --dest-sheet Analysis --dest-cell A1 --pivot-table SalesPivot
excelcli pivottable add-row-field --session 1 --pivot-table SalesPivot --field Region
excelcli pivottable add-value-field --session 1 --pivot-table SalesPivot --field Amount --function Sum

VBA automation:

excelcli vba import --session 1 --module "Helpers" --code-file helpers.vba
excelcli vba run --session 1 --macro "Helpers.ProcessData"

⚙️ System Requirements

Note: ExcelMcp.CLI controls the actual Excel application via COM interop, not just file formats. This provides access to Power Query, VBA runtime, formula engine, and all Excel features, but requires Excel to be installed.

🔒 VBA Operations Setup (One-Time)

VBA commands require "Trust access to the VBA project object model" to be enabled:

1. Open Excel
2. Go to File → Options → Trust Center
3. Click "Trust Center Settings"
4. Select "Macro Settings"
5. Check "✓ Trust access to the VBA project object model"
6. Click OK twice

This is a security setting that must be manually enabled. ExcelMcp.CLI never modifies security settings automatically.

For macro-enabled workbooks, use .xlsm extension:

excelcli session create macros.xlsm
# Returns session ID (e.g., 1)
excelcli vba import --session 1 --module MyModule --code-file code.vba
excelcli session close --session 1 --save

📖 Complete Documentation

• NuGet Package - .NET Global Tool installation
• GitHub Repository - Source code and issues
• Release Notes - Latest updates

🚧 Troubleshooting

Command Not Found After Installation

# Verify .NET tools path is in your PATH environment variable
dotnet tool list --global

# If excelcli is listed but not found, add .NET tools to PATH:
# The default location is: %USERPROFILE%\.dotnet\tools

Excel Not Found

# Error: "Microsoft Excel is not installed"
# Solution: Install Microsoft Excel (any version 2016+)

VBA Access Denied

# Error: "Programmatic access to Visual Basic Project is not trusted"
# Solution: Enable VBA trust (see VBA Operations Setup above)

Permission Issues

# Run PowerShell/CMD as Administrator if you encounter permission errors
# Or install to user directory: dotnet tool install --global Sbroenne.ExcelMcp.CLI

🛠️ Advanced Usage

Scripting & Automation

# PowerShell script example
$files = Get-ChildItem *.xlsx
foreach ($file in $files) {
    $session = excelcli session open $file.Name | Select-String "Session ID: (.+)" | ForEach-Object { $_.Matches.Groups[1].Value }
    excelcli powerquery refresh --session $session --query "Sales Data"
    excelcli datamodel refresh --session $session
    excelcli session close $session --save
}

CI/CD Integration

# GitHub Actions example
- name: Install ExcelMcp.CLI
  run: dotnet tool install --global Sbroenne.ExcelMcp.CLI

- name: Process Excel Files
  run: |
    SESSION=$(excelcli session open data.xlsx | grep "Session ID:" | cut -d' ' -f3)
    excelcli powerquery create --session $SESSION --query "Query1" --mcode-file queries/query1.pq
    excelcli powerquery refresh --session $SESSION --query "Query1"
    excelcli session close $SESSION --save

✅ Tested Scenarios

The CLI ships with real Excel-backed integration tests that exercise the session lifecycle plus worksheet creation/listing flows through the same commands you run locally. Execute them with:

dotnet test tests/ExcelMcp.CLI.Tests/ExcelMcp.CLI.Tests.csproj --filter "Layer=CLI"

These tests open actual workbooks, issue session open/list/close, and call excelcli sheet actions to ensure the command pipeline stays healthy.

🤝 Related Tools

• ExcelMcp.McpServer - MCP server for AI assistant integration
• Excel MCP VS Code Extension - One-click Excel automation in VS Code

📄 License

MIT License - see LICENSE for details.

🙋 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Complete Docs

Built with ❤️ for Excel developers and automation engineers