Command-line interface for Excel manipulation. Designed for agents and scripts.
Every command is stateless and includes the source file as a parameter. No interactive mode, no shell persistence.
xlforge <command> <file.xlsx> [options]xlforge uses a Hybrid Engine architecture:
| Engine | When Used | Capabilities |
|---|---|---|
| xlwings | Excel installed | Full control: cells, formatting, charts, macros |
| openpyxl | Headless/Docker | Read/write cells, sheet ops, basic formatting |
The engine is auto-detected. Use --engine <name> to force a specific engine.
xlforge cell get report.xlsx "A1" # Auto-detect
xlforge cell get report.xlsx "A1" --engine xlwings # Force xlwings
xlforge cell get report.xlsx "A1" --engine openpyxl # Force openpyxlNote: Some commands (chart, validation) require xlwings. In headless mode, these return error code 9: Feature requires Excel.
- Agent-first - Every command is a standalone shell operation
- Auto-save with safety - Changes save automatically (use
--dry-runto preview) - JSON everywhere - All commands support
--json; errors can be returned as JSON via--json-errors - Fail fast with retry - Exponential backoff on file lock (max 3 attempts)
- Context-aware - Support for default file/sheet via environment or
usecommand - Transaction-safe - Batch operations can be wrapped in transactions
# Essential commands
xlforge file open <file> # Open/create file
xlforge file save <file> # Save changes
xlforge file info <file> # Show metadata + PID
# Cell operations
xlforge cell get <file> <cell> [--json] # Read cell
xlforge cell set <file> <cell> <value> # Write cell
xlforge cell formula <file> <cell> <f> # Set formula
# Context (reduces repetition)
xlforge use <file> [--sheet <name>] # Set default context
xlforge context # Show current context
# SQL Bridge (DuckDB-powered)
xlforge sql query "<query>" # Query Excel/CSV/DB
xlforge sql push "<query>" --db <url> --to <file> <table>
xlforge sql pull <file> <range> --into <url>
# Batch (fast, single COM session)
xlforge run <script.xlf> [--dry-run] [--transaction]
# AI Context (semantic search + describe)
xlforge index create <file> --engine local --privacy-check # Local-first indexing
xlforge query <file> "Net Profit" --coordinate # Find by meaning
xlforge describe <file> <range> --schema-only --json # LLM-optimized schema
# Macro Recorder (transform user actions into scripts)
xlforge record start <file> --interactive # Teacher mode
xlforge record stop --clean # Normalize + save- Context Management - Environment variables and
usecommand - Batch Execution - Run scripts in single COM session
- Examples - Complete workflow examples
- File Commands - open, save, close, info, kill
- Sheet Commands - list, create, delete, rename, copy, use
- Cell Commands - get, set, formula, clear, copy, bulk
- Format Commands - cell, range, apply
- Column & Row Commands - width, auto-fit, height
- Data Commands - import csv, export csv
- Table Commands - create, link, sync-schema, refresh
- Chart Commands - create
- Validation Commands - create
- Protection Commands - freeze, protect, unprotect
- App Commands - visible, calculate, focus, alert, wait-idle, screen-update
- Checkpoint Commands - Git-like versioning for Excel
- Semantic Commands - index, query, describe (AI context)
- Watch Commands - Reactive triggers
- SQL Commands - query, push, pull, connect
- Reference - Error codes, global flags, retry mechanism
v1.1.0 - 2026-03-31 (AI-native features: semantic search, describe with sampling, macro recorder)