CLI
The SheetXL CLI is a powerful command-line tool for automating spreadsheet operations, running scripts, and managing workbooks programmatically.
Installation
The easiest way to use the SheetXL CLI is by running it directly without a permanent installation. All you need is Node.js (v22+) installed (v24 recommended),
Open your terminal and run:
npx sheetxl@beta
(If you use pnpm, you can use dlx sheetxl)
This will start an interactive REPL (Read-Eval-Print Loop), pre-loaded with the SheetXL SDK.
SheetXL >
Type help in CLI for a list of commands.
Usage
sheetxl [options] [workbook]
The workbook is the trailing positional argument. Omit it and you get a blank workbook. One rule decides everything else:
Give it code and it runs, prints, and exits. Give it none and you get an interactive session.
Code means -e, -f, or source piped on stdin.
| You type | You get |
|---|---|
sheetxl | interactive session, blank workbook |
sheetxl book.xlsx | interactive session, wb loaded |
sheetxl -e "wb.getSheet()" book.xlsx | evaluate, print, exit |
sheetxl -f script.ts book.xlsx | run a script file, exit |
sheetxl -i -f setup.ts book.xlsx | run the script, then stay interactive |
sheetxl book.xlsx --out book.csv | convert; no code needed |
If you know duckdb or sqlite3, you already know this shape — the difference is that SheetXL takes TypeScript where they take SQL. And it is the same TypeScript for asking a question and for changing the workbook, so nothing distinguishes a "query" from a "script."
Reading
-e takes an expression, and the value of its final expression is rendered:
npx sheetxl@beta -e "wb" book.xlsx # workbook report
npx sheetxl@beta -e "wb.getSheet('Sales')" book.xlsx # sheet report
npx sheetxl@beta -e "wb.getRange('B2:D9').getStats()" book.xlsx # min/max/mean/…
await is implicit — never write it. wb, log, warn, error, and args are ambient.
Returning a subject describes it, so there is no separate describe or query command to learn. Reports render as markdown by default; use --json for the raw value.
Writing
Nothing is written unless you ask.
npx sheetxl@beta -e "wb.getRange('B2').setValue('42%')" book.xlsx --save # in place
npx sheetxl@beta -e "wb.getRange('B2').setValue('42%')" book.xlsx --out new.xlsx # elsewhere
Executing Scripts
For automation and more complex tasks, pass a local script file with -f. It runs within the SheetXL environment with the SDK available, and it is repeatable — each script receives the workbook the previous one left behind.
npx sheetxl@beta -f path/to/your/script.ts book.xlsx
npx sheetxl@beta -f normalize.ts -f summarize.ts book.xlsx --save
A file with no default export behaves exactly like -e. A file with a default export is handed the run context, and its return value is the result.
Everything after -- reaches the script as args:
npx sheetxl@beta -f summarize.ts book.xlsx -- --sheet Q3
Interactive Sessions
Starting with no code drops you into an interactive session with @sheetxl/sdk and @sheetxl/io loaded. Name a workbook and it arrives as wb.
npx sheetxl@beta book.xlsx
Create a new workbook and save it with a single value:
wb = new Workbook();
wb.getRange('a1').setValues([[1]]);
save('myWorkbook.xlsx', wb);
help: Displays help message..help: Shows all available dot commands.
Use -i to run code first and stay in the session:
npx sheetxl@beta -i -f fixtures.ts book.xlsx
See our full SDK API Documentation for a complete list of all available classes and methods.
Direct Commands
Commands cover the things that are not "operate on this workbook."
npx sheetxl@beta grep "Q[1-4] Total" book.xlsx # search cell contents
npx sheetxl@beta info # engine readiness and environment
npx sheetxl@beta mcp # run as an MCP server
npx sheetxl@beta help # help for any command
Activate Your License
To activate your license key, run the activate command:
npx sheetxl@beta activate YOUR_LICENSE_KEY_HERE
This will store your license key for future use.