https://github.com/wareflowx/xlforge
A command-line interface for Excel manipulation. Designed for agents and scripts.
https://github.com/wareflowx/xlforge
ai-tools automation cli duckdb excel excel-automation openpyxl python scripting xlwings
Last synced: 25 days ago
JSON representation
A command-line interface for Excel manipulation. Designed for agents and scripts.
- Host: GitHub
- URL: https://github.com/wareflowx/xlforge
- Owner: wareflowx
- Created: 2026-04-02T06:53:51.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T11:29:00.000Z (3 months ago)
- Last Synced: 2026-04-02T20:27:51.311Z (3 months ago)
- Topics: ai-tools, automation, cli, duckdb, excel, excel-automation, openpyxl, python, scripting, xlwings
- Language: Python
- Homepage: https://xforge.nesalia.com
- Size: 169 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
xlforge
> A command-line interface for Excel manipulation. Designed for agents and scripts.
## About
xlforge is a powerful CLI for Excel manipulation built with an agent-first philosophy. Every command is stateless and includes the source file as a parameter, making it perfect for automation, scripts, and AI integrations.
Similar to how a robust build tool provides declarative commands for complex tasks, xlforge provides a comprehensive set of commands for Excel operations - from basic cell manipulation to advanced features like SQL queries, semantic search, and macro recording.
xlforge uses a **Hybrid Engine** architecture that automatically selects the best approach:
- **xlwings** when Excel is installed - full control including cells, formatting, charts, and macros
- **openpyxl** for headless/Docker environments - read/write cells, sheet operations, and basic formatting
## Philosophy
- **Agent-first** - Every command is a standalone shell operation
- **Stateless** - No interactive mode, no shell persistence
- **JSON everywhere** - All commands support JSON output; errors can be returned as JSON
- **Fail fast with retry** - Exponential backoff on file lock (max 3 attempts)
- **Transaction-safe** - Batch operations can be wrapped in transactions
## Features
- Cell operations - get, set, formula, clear, copy, bulk operations
- Sheet management - create, delete, rename, copy, use
- Formatting - cell styles, number formats, borders, colors
- Data import/export - CSV, Excel tables, database sync
- Charts and validations - create and manage Excel objects
- SQL Bridge - Query Excel, CSV, and databases using DuckDB
- Semantic search - AI-powered cell finding by meaning
- Macro recorder - Transform user actions into reusable scripts
- Checkpoint versioning - Git-like versioning for Excel files
- Batch execution - Run scripts in a single COM session
## Quick Start
```bash
# Install xlforge
pip install xlforge
# Read a cell
xlforge cell get report.xlsx "A1"
# Write to a cell
xlforge cell set report.xlsx "A1" "Hello World"
# Set a formula
xlforge cell formula report.xlsx "B1" "=SUM(A:A)"
# Set context to avoid repeating filename
xlforge use report.xlsx --sheet Data
cell set A1 "Value" # Operates on Data!A1 in report.xlsx
# Run a batch script
xlforge run script.xlf --transaction
```
## Documentation
- [Getting Started](docs/README.md) - Overview and architecture
- [Context Management](docs/context.md) - Environment variables and default context
- [Batch Execution](docs/batch.md) - Run scripts with transaction support
- [Examples](docs/examples.md) - Complete workflow examples
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see the [LICENSE](LICENSE) file for details.