docs.sheetjs.com/docz/docs/03-demos/19-desktop/09-cli.md

---
title: Command-Line Tools
pagination_prev: demos/mobile/index
pagination_next: demos/data/index
sidebar_custom_props:
  cli: true
---

import current from '/version.js';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';

With the availability of JS engines and the success of server-side platforms,
it is feasible to build command-line tools for various workflows.

This demo covers a number of strategies for building standalone processors. The
goal is to generate CSV output from an arbitrary spreadsheet file.

:::tip pass

The [`xlsx-cli`](https://cdn.sheetjs.com/xlsx-cli/) NodeJS script is available
as a package on the SheetJS CDN. It is an easy-to-use command-line tool for
translating files between supported spreadsheet file formats.

:::

## NodeJS

There are a few popular tools for compiling NodeJS scripts to CLI programs.

The demo script presents a friendly command line interface including flags:

```bash
$ ./xlsx-cli -h
Usage: xlsx-cli [options] <file> [sheetname]

Options:
  -V, --version            output the version number
  -f, --file <file>        use specified workbook
  -s, --sheet <sheet>      print specified sheet (default first sheet)
...
```

:::note Tested Deployments

This demo was tested in the following deployments:

<Tabs groupId="njs">
  <TabItem value="nexe" label="Nexe">

| Architecture | Version      | Node Target | Date       |
|:-------------|:-------------|:------------|:-----------|
| `darwin-x64` | `4.0.0-rc.2` | `14.15.3`   | 2023-10-10 |
| `darwin-arm` | `4.0.0-rc.2` | `18.18.0`   | 2023-12-01 |
| `win10-x64`  | `4.0.0-rc.2` | `14.15.3`   | 2023-10-09 |
| `win11-arm`  | `4.0.0-rc.2` | `20.10.0`   | 2023-12-01 |
| `linux-x64`  | `4.0.0-rc.2` | `14.15.3`   | 2023-12-07 |
| `linux-arm`  | `4.0.0-rc.2` | `20.10.0`   | 2023-12-01 |

  </TabItem>
  <TabItem value="pkg" label="pkg">

| Architecture | Version | Node Target | Date       |
|:-------------|:--------|:------------|:-----------|
| `darwin-x64` | `5.8.1` | `18.5.0`    | 2023-10-11 |
| `darwin-arm` | `5.8.1` | `18.5.0`    | 2023-12-01 |
| `win10-x64`  | `5.8.1` | `18.5.0`    | 2023-10-09 |
| `win11-arm`  | `5.8.1` | `18.5.0`    | 2023-12-01 |
| `linux-x64`  | `5.8.1` | `18.5.0`    | 2023-12-07 |
| `linux-arm`  | `5.8.1` | `18.5.0`    | 2023-12-01 |

  </TabItem>
  <TabItem value="boxednode" label="boxednode">

| Architecture | Version | Node Target | Date       |
|:-------------|:--------|:------------|:-----------|
| `darwin-x64` | `2.1.2` | `20.8.0`    | 2023-10-12 |
| `darwin-arm` | `2.3.0` | `21.3.0`    | 2023-12-01 |
| `win10-x64`  | `2.1.2` | `16.20.2`   | 2023-10-09 |
| `linux-x64`  | `2.3.0` | `21.4.0`    | 2023-12-07 |
| `linux-arm`  | `2.3.0` | `21.3.0`    | 2023-12-01 |

  </TabItem>
</Tabs>

:::

0) Download the test file <https://sheetjs.com/pres.numbers>:

```bash
curl -LO https://sheetjs.com/pres.numbers
```

1) Download [`xlsx-cli.js`](pathname:///cli/xlsx-cli.js)

```bash
curl -LO https://docs.sheetjs.com/cli/xlsx-cli.js
```

2) Install the dependencies:

<Tabs groupId="pm">
  <TabItem value="npm" label="npm">
<CodeBlock language="bash">{`\
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
</CodeBlock>
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
<CodeBlock language="bash">{`\
pnpm install https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
</CodeBlock>
  </TabItem>
  <TabItem value="yarn" label="Yarn" default>
<CodeBlock language="bash">{`\
yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`}
</CodeBlock>
  </TabItem>
</Tabs>

3) Follow tooling steps:

<Tabs groupId="njs">
  <TabItem value="nexe" label="Nexe">

Run `nexe` and manually specify NodeJS version 14.15.3

```bash
npx nexe -t 14.15.3 xlsx-cli.js
```

This generates `xlsx-cli` or `xlsx-cli.exe` depending on platform.

:::caution pass

When the demo was tested on ARM targets, the Nexe pre-built packages were
missing.  The package must be built from source:

```bash
npx nexe xlsx-cli.js --build --python=$(which python3) --make="-j8"
```

:::

:::caution pass

On Windows ARM, the target `windows-arm64-20.10.0` must be specified:

```bash
npx nexe xlsx-cli.js --build --make="-j8" --target=windows-arm64-20.10.0
```

The Windows build may fail with a `vcbuild.bat` error:

```
Error: vcbuild.bat nosign release arm64 exited with code: 1
```

Pass the `-v` flag for more details. In the most recent test, the error stemmed
from a Python version mismatch:

```
Node.js configure: found Python 2.7.18
Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6
```

The resolved version of Python can be found with

```cmd
where python
```

In the most recent test, a Python 2 version appeared first. This was fixed by
finding the Python 3 location and prepending it to `PATH`:

```cmd
set PATH="C:\correct\path\to\python\three";%PATH%
```

:::

  </TabItem>
  <TabItem value="pkg" label="pkg">

:::warning pass

When this demo was last tested, `pkg` failed with an error referencing `node20`:

```
> Targets not specified. Assuming:
  node20-linux-arm64, node20-macos-arm64, node20-win-arm64
> Error! No available node version satisfies 'node20'
```

**`pkg` does not support NodeJS 20!**

The local NodeJS version must be rolled back to version 18.

If `n` is installed:

```bash
sudo n 18
```

If `nvm` was used to install NodeJS:

```bash
nvm install 18
nvm use 18
```

:::

Run `pkg`:

```bash
npx pkg xlsx-cli.js
```

This generates `xlsx-cli-linux`, `xlsx-cli-macos`, and `xlsx-cli-win.exe` .

  </TabItem>
  <TabItem value="boxednode" label="boxednode">

Run `boxednode`:

<Tabs groupId="os">
  <TabItem value="unix" label="Linux/MacOS">

```bash
npx boxednode@2.3.0 -s xlsx-cli.js -t xlsx-cli
```

  </TabItem>
  <TabItem value="win" label="Windows">

```bash
npx boxednode@2.1.2 -s xlsx-cli.js -t xlsx-cli.exe -n 16.20.2
```

:::info pass

The Windows 10 build requires Visual Studio with "Desktop development with C++"
workload, Python 3, and NASM[^1].

The build command should be run in "x64 Native Tools Command Prompt"

:::

:::caution pass

When the demo was last tested on Windows, the build failed:

```
error MSB8020: The build tools for Visual Studio 2019 (Platform Toolset = 'v142') cannot be found. To build using the v142 build tools, please install Visual Studio 2019 build tools.
```

This error was fixed by installing the `v142` build tools through the Visual
Studio installer.

:::

:::caution pass

In the most recent Windows test against NodeJS `20.8.0`, the build failed due
to an issue in the OpenSSL dependency:

```
...\node-v20.8.0\deps\openssl\openssl\crypto\cversion.c(75,33): error C2153: integer literals must have at least one digit [...\node-v20.8.0\deps\openssl\openssl.vcxproj]
```

SheetJS libraries are compatible with NodeJS versions dating back to `v0.8`. The
workaround is to select NodeJS `v16.20.2` using the `-n` flag. This version was
was chosen since NodeJS `v18` upgraded the OpenSSL dependency.

:::

  </TabItem>
</Tabs>

  </TabItem>
</Tabs>

4) Run the generated program, passing `pres.numbers` as the argument. For
example, `nexe` generates `xlsx-cli` in macOS so the command is:

```bash
./xlsx-cli pres.numbers
```

`nexe` generates `xlsx-cli.exe` in Windows, so the command is:

```powershell
.\xlsx-cli.exe pres.numbers
```

## V8

The [V8](/docs/demos/engines/v8) demo covers standalone programs that embed the
V8 engine. This demo uses the Rust integration to generate a command line tool.

:::note Tested Deployments

This demo was last tested in the following deployments:

| Architecture | V8 Version    | Crate    | Date       |
|:-------------|:--------------|:---------|:-----------|
| `darwin-x64` | `11.8.172.13` | `0.79.2` | 2023-10-12 |
| `darwin-arm` | `11.8.172.13` | `0.79.2` | 2023-10-18 |
| `win10-x64`  | `11.8.172.13` | `0.79.2` | 2023-10-09 |
| `win11-x64`  | `11.8.172.13` | `0.79.2` | 2023-10-14 |
| `linux-x64`  | `11.8.172.13` | `0.79.2` | 2023-10-11 |
| `linux-arm`  | `12.0.267.8`  | `0.82.0` | 2023-12-01 |

:::

0) Make a new folder for the project:

```bash
mkdir sheetjs2csv
cd sheetjs2csv
```

1) Download the following scripts:

- [`Cargo.toml`](pathname:///cli/Cargo.toml)
- [`snapshot.rs`](pathname:///cli/snapshot.rs)
- [`sheet2csv.rs`](pathname:///cli/sheet2csv.rs)

```bash
curl -LO https://docs.sheetjs.com/cli/Cargo.toml
curl -LO https://docs.sheetjs.com/cli/snapshot.rs
curl -LO https://docs.sheetjs.com/cli/sheet2csv.rs
```

2) Download the SheetJS Standalone script and move to the project directory:

<ul>
<li><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}>xlsx.full.min.js</a></li>
</ul>

<CodeBlock language="bash">{`\
curl -LO https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`}
</CodeBlock>

3) Build the V8 snapshot:

```bash
cargo build --bin snapshot
cargo run --bin snapshot
```

:::caution pass

With some versions of the `v8` crate, the Linux AArch64 build failed with an error:

```
error[E0080]: evaluation of constant value failed

     |
1715 |   assert!(size_of::<TypeId>() == size_of::<u64>());
     |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at 'assertion failed: size_of::<TypeId>() == size_of::<u64>()'
```

Versions `0.75.1` and `0.82.0` are known to work.

:::


4) Build `sheet2csv` (`sheet2csv.exe` in Windows):

```bash
cargo build --release --bin sheet2csv
```

5) Download the test file <https://sheetjs.com/pres.numbers>:

```bash
curl -LO https://sheetjs.com/pres.numbers
```

6) Test the application:

<Tabs groupId="os">
  <TabItem value="unix" label="Linux/MacOS">

```bash
mv target/release/sheet2csv .
./sheet2csv pres.numbers
```

  </TabItem>
  <TabItem value="win" label="Windows">

```bash
mv target/release/sheet2csv.exe .
.\sheet2csv.exe pres.numbers
```

  </TabItem>
</Tabs>

## Deno

`deno compile` generates a standalone executable that includes the entire JS
runtime as well as user JS code.

When compiling, the `--allow-read` option must be specified to allow the script
to read files from the filesystem with `Deno.readFileSync`.

<https://docs.sheetjs.com/cli/sheet2csv.ts> can be compiled and run from Deno.

:::note Tested Deployments

This demo was last tested in the following deployments:

| Architecture | Version  | Date       |
|:-------------|:---------|:-----------|
| `darwin-x64` | `1.37.1` | 2023-10-12 |
| `darwin-arm` | `1.37.2` | 2023-10-18 |
| `win10-x64`  | `1.37.1` | 2023-10-09 |
| `win11-x64`  | `1.37.2` | 2023-10-14 |
| `win11-arm`  | `1.38.4` | 2023-12-01 |
| `linux-x64`  | `1.39.4` | 2024-01-22 |
| `linux-arm`  | `1.38.4` | 2023-12-01 |

:::

0) Install Deno.[^2]

1) Download the test file <https://sheetjs.com/pres.numbers>:

```bash
curl -LO https://sheetjs.com/pres.numbers
```

2) Test the script with `deno run`:

```bash
deno run -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts pres.numbers
```

If this worked, the program will print a CSV of the first worksheet.

3) Compile and run `sheet2csv`:

```bash
deno compile -r --allow-read https://docs.sheetjs.com/cli/sheet2csv.ts
./sheet2csv pres.numbers
```

## Dedicated Engines

The following demos for JS engines produce standalone programs:

- [Duktape](/docs/demos/engines/duktape)
- [ChakraCore](/docs/demos/engines/chakra)
- [QuickJS](/docs/demos/engines/quickjs)
- [Goja](/docs/demos/engines/goja)
- [JavaScriptCore](/docs/demos/engines/jsc)

[^1]: Downloads can be found [at the main NASM project website](https://www.nasm.us/)
[^2]: [The official instructions](https://docs.deno.com/runtime/manual/getting_started/installation) cover most platforms. Deno does not provide official Linux ARM64 builds, but [there are unofficial community builds](https://github.com/LukeChannings/deno-arm64).