Installing the VTEX IO CLI

According to your operating system, take the respective steps to install VTEX IO’s CLI on your machine.

MacOS

Brew

For machines running on Apple M1 chip, before installing VTEX IO CLI, install Rosetta and enable the machine to use the command-line interface for a Mac with an Intel processor. To install Rosetta, run the following in your terminal: /usr/sbin/softwareupdate --install-rosetta --agree-to-license.

Install Homebrew by following the instructions on Homebrew website.

{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAFUlEQVR4nGPgZWf48ebO/2/P5KVEASYYBf4wEU3bAAAAAElFTkSuQmCC","img":{"src":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-vtex-io-cli-install-0.png","width":832,"height":152,"type":"png"}}

Then, install VTEX IO'S CLI by running the following command.

brew tap vtex/vtex
brew install vtex

Linux

Tarball

Before the installation, check if you have the curl command-line tool and library installed on your machine.

Open the terminal and run the following command to install the VTEX IO CLI.
```
curl -L https://vtex.io/vtexcli/install | sh
```

Windows

Installer for Windows

Download the appropriate installer for your Windows system (64-bit installer; 32-bit installer).
Open the downloaded file and follow the instructions to finish the installation process.
Run the Windows Terminal with elevated administrator permission by right-clicking on the Windows Terminal icon and selecting "Run as administrator."
Run the following command to complete the installation.

vtex

To which will appear the following message.

{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAABCAIAAAB2XpiaAAAACXBIWXMAABJ0AAASdAHeZh94AAAAFUlEQVR4nGO4c/v24kULra2tRUREAC9zBWaYiU3xAAAAAElFTkSuQmCC","img":{"src":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-vtex-io-cli-install-1.png","width":812,"height":121,"type":"png"}}

For the next step, you won't need to be in your admin role.

Installing the CLI via NPM

Since VTEX IO's CLI is built with Node.js, you can manually install it via npm. This method is recommended only for environments in which auto-updating VTEX IO's CLI is not ideal.

We strongly recommend using an alternative installation method. If you opt to use npm to install the VTEX IO CLI, keep in mind that the CLI won't be automatically updated, and the Node version on your machine might conflict with the one used by the CLI developers. Preferably, if you opt for any other installation method, VTEX IO's CLI will always be up-to-date, and you will avoid installation issues.

MacOS

Install Homebrew by following the instructions on Homebrew website.

Install Node.js via Homebrew by running the following command.

brew install node

Then, install Yarn.

brew install yarn

Finally, install the VTEX IO CLI.

yarn global add vtex

Linux

Install Node.js by running the following command.

sudo apt install nodejs

Install Yarn by following the Yarn installation for Linux.
Install the VTEX IO CLI by running the following command.

sudo yarn global add vtex

Windows

Download and install Node.js.
Download and install Yarn.
Run the Windows Terminal with elevated administrator permission by right-clicking on the Windows Terminal icon and selecting "Run as administrator.
Install the VTEX IO CLI by running the following command.

yarn global add vtex

Run the following command to complete the installation.

vtex

To which will appear the following message.

For the next step, you won't need to be in your admin role.

Verifying the installation

To confirm that the installation occurred as expected, run the following command to check all default commands available in VTEX IO's CLI.

vtex

{"base64":" ","img":{"width":2206,"height":1302,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":307862,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-io-documentation-vtex-io-cli-install-4.png"}}

Troubleshooting

If VTEX IO's CLI is not behaving as expected, run vtex --version to make sure you're using the latest version available. If not, consider updating it.

If the problem persists, check the following instructions.

Error: Cannot find module 'vtex'

This error is related to plugins detached from the VTEX IO's CLI base code.

Even though plugins are decoupled from VTEX IO's CLI, they rely on the CLI functionalities. Therefore, this error signalizes that these plugins are failing to access VTEX IO's CLI functionalities.

To solve this problem, you will need to create a symlink from {vtex-folder}/node_modules/vtex to {vtex-folder}/.

According to your operating system, run the following command in the terminal to create a symlink:

MacOS

ln -s /usr/local/Cellar/vtex/2.119.2/libexec /usr/local/Cellar/vtex/2.119.2/libexec/node_modules/vtex

Linux

ln -s /usr/local/lib/vtex /usr/local/lib/vtex/node_modules/vtex

If the error persists, don't hesitate to open a support ticket.