--- title: Command-Line Tools pagination_prev: demos/desktop/index pagination_next: demos/data/index --- import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; With the availability of JS engines and the success of server-side platforms, it is possible to build standalone command-line tools from JavaScript code. [SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing data from spreadsheets. This demo covers a number of strategies for building standalone spreadsheet processors. The ultimate goal is to use SheetJS libraries to generate CSV output from arbitrary spreadsheet files. The generated command-line tool will accept an argument, parse the specified workbook, and print CSV rows to the terminal. >**Sample terminal session** ```bash $ xlsx-cli.exe pres.numbers Name,Index Bill Clinton,42 GeorgeW Bush,43 Barack Obama,44 Donald Trump,45 Joseph Biden,46 ``` Demos for common standalone CLI tools are included in separate pages: :::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. ::: :::caution pass For most common deployment scenarios, it is possible to install a server-side platform such as [NodeJS](/docs/getting-started/installation/nodejs). **It is strongly recommended to use a dedicated platform when possible.** The standalone programs generated in this demo are useful when a dedicated server-side scripting platform cannot be installed on the target computer. ::: ## 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] [sheetname] Options: -V, --version output the version number -f, --file use specified workbook -s, --sheet print specified sheet (default first sheet) ... ``` :::note Tested Deployments This demo was tested in the following deployments: | Architecture | Version | NodeJS | Source | Date | |:-------------|:-------------|:----------|:----------|:-----------| | `darwin-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-03-15 | | `darwin-arm` | `4.0.0-rc.6` | `18.20.3` | Compiled | 2024-05-25 | | `win10-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-04-18 | | `win11-arm` | `4.0.0-rc.2` | `20.10.0` | Compiled | 2023-12-01 | | `linux-x64` | `4.0.0-rc.4` | `14.15.3` | Pre-built | 2024-03-21 | | `linux-arm` | `4.0.0-rc.2` | `20.10.0` | Compiled | 2023-12-01 | | Architecture | Version | NodeJS | Date | |:-------------|:--------|:---------|:-----------| | `darwin-x64` | `5.8.1` | `18.5.0` | 2024-03-15 | | `darwin-arm` | `5.8.1` | `18.5.0` | 2024-05-25 | | `win10-x64` | `5.8.1` | `18.5.0` | 2024-04-18 | | `win11-arm` | `5.8.1` | `18.5.0` | 2023-12-01 | | `linux-x64` | `5.8.1` | `18.5.0` | 2024-03-21 | | `linux-arm` | `5.8.1` | `18.5.0` | 2023-12-01 | | Architecture | Version | NodeJS | Date | |:-------------|:--------|:----------|:-----------| | `darwin-x64` | `2.4.0` | `21.7.1` | 2024-03-15 | | `darwin-arm` | `2.4.3` | `22.2.0` | 2024-05-25 | | `win10-x64` | `2.4.2` | `16.20.2` | 2024-04-18 | | `linux-x64` | `2.4.0` | `21.7.1` | 2024-03-21 | | `linux-arm` | `2.3.0` | `21.3.0` | 2023-12-01 | ::: 0) Download the test file https://docs.sheetjs.com/pres.numbers: ```bash curl -o pres.numbers https://docs.sheetjs.com/pres.numbers ``` 1) Download [`xlsx-cli.js`](pathname:///cli/xlsx-cli.js) ```bash curl -o xlsx-cli.js https://docs.sheetjs.com/cli/xlsx-cli.js ``` 2) Install the dependencies: {`\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} {`\ pnpm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} {`\ yarn add https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz exit-on-epipe commander@2`} 3) Follow tooling steps: 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% ``` ::: :::danger 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` . Run `boxednode`: ```bash npx boxednode@2.4.0 -s xlsx-cli.js -t xlsx-cli ``` ```bash npx boxednode@2.4.0 -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.11, and NASM[^1]. **The build command must be run in "x64 Native Tools Command Prompt"** ::: :::caution pass When the demo was last tested, the build failed: ``` Not an executable Python program Could not find Python. ``` By default, Windows aliases `python` to a Microsoft Store installer. If the official installer was used, the alias should be disabled manually: 1) Open Start menu and type "app alias". Click "Manage app execution aliases". 2) Disable the App Installer for all items with `python` in the name. Using Python 3.12, the build fails with an error: ``` Please use python3.11 or python3.10 or python3.9 or python3.8 or python3.7 or python3.6. ``` In the most recent test, Python 3.11.8 was installed from the official site. ::: :::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. ::: 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` | `12.3.219.9` | `0.88.0` | 2024-03-15 | | `darwin-arm` | `12.6.228.3` | `0.92.0` | 2024-05-23 | | `win10-x64` | `12.3.219.9` | `0.88.0` | 2024-03-24 | | `win11-x64` | `12.6.228.3` | `0.92.0` | 2024-05-23 | | `linux-x64` | `12.3.219.9` | `0.88.0` | 2024-03-18 | | `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 -o Cargo.toml https://docs.sheetjs.com/cli/Cargo.toml curl -o snapshot.rs https://docs.sheetjs.com/cli/snapshot.rs curl -o sheet2csv.rs https://docs.sheetjs.com/cli/sheet2csv.rs ``` 2) Download the SheetJS Standalone script and move to the project directory: {`\ curl -o xlsx.full.min.js https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js`} 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::() == size_of::()); | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the evaluated program panicked at 'assertion failed: size_of::() == size_of::()' ``` 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://docs.sheetjs.com/pres.numbers: ```bash curl -o pres.numbers https://docs.sheetjs.com/pres.numbers ``` 6) Test the application: ```bash mv target/release/sheet2csv . ./sheet2csv pres.numbers ``` ```bash mv target/release/sheet2csv.exe . .\sheet2csv.exe pres.numbers ``` #### Deno **[The exposition has been moved to a separate page.](/docs/demos/cli/deno)** ## 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/)