Accessing the list of commands

Start using the VTEX IO CLI by running the following command to access a summary of the CLI's default commands.

$ vtex help

VTEX commandVTEX command


Check the Command Reference for more details.

Logging into your VTEX account

Log in to your VTEX account by running the following command.

$ vtex login {account-name}


Replace the value between curly braces according to your scenario.

After you run this command, a new tab will open on your browser, asking you to log in to the desired VTEX account with your email.

Once you log in, the web page will display the following message: “You may now close this window.”

Now, when you go back to the computer terminal, you'll have access to a development environment for this VTEX account. You'll see some basic information about your account as in the following.

Login ScreenLogin Screen


If you later decide to work on another account, run vtex switch {account-name}, specifying the account name you want to switch to.

Creating a new workspace

After you log in to a VTEX account, you'll be automatically taken to the master workspace, meaning the version publicly available to end-users.

To start customizing your storefront or developing a VTEX IO app, you must switch from the master workspace to a development one.

To switch to an existing development workspace or create a new one, run the following command:

$ vtex use {workspace-name}

Notice that if a workspace with the chosen name already exists, you'll be taken to it.

Change WorkspaceChange Workspace

Otherwise, you'll be asked if you want to create it.

New WorkspaceNew Workspace

From now on, every operation performed will happen in the specified workspace.

Verifying your environment

Confirm the account you're logged into and which workspace you're currently using by running the following command.

$ vtex whoami

Installing an app

Install an app on your current account and workspace by running the following command.

$ vtex install {appvendor}.{appname}@{appversion}


Replace the value between curly braces according to your scenario.

If you try to install an app that has Billing Options, you first need to access the VTEX App Store and agree to the app's terms and conditions.

Billing OptionsBilling Options

  1. If you type Y, the app's page you intend to install from the VTEX App Store will open in your browser.
  2. To continue with the installation, click on GET APP > CONFIRM to log in to your VTEX store.
  3. Read and agree to the app's terms and conditions


Notice that some apps are free and others will have specific methods of charging.

Starting a new project

Start a new project from pre-defined templates by running the following command.

$ vtex init

Init commandInit command

For example, to start developing a store theme app, choose the store option. This will clone the Store Theme boilerplate app into your local files.

Developing locally

Change to the directory of the app you're developing and run the following command to sync your local files with the VTEX platform.

$ vtex link

Link CommandLink Command

VTEX IO's CLI will monitor your files and provide an URL related to that workspace. You'll be able to access it through https://{workspace}--{account}, by replacing the value between curly braces with the name of the workspace previously created and your VTEX account. For example,

By accessing this URL, you'll be able to watch for local changes in the linked files.

Checking the installed apps

List all apps installed on the current account by running the following command.

$ vtex list

Installed apps are classified as in the following:

  1. Apps automatically installed by your account's Edition App.
  2. Apps manually installed on the current workspace.
  3. Apps linked to the current workspace.

Authenticating API requests

When developing with VTEX IO, instead of using an appKey and appToken pair, you must use a VTEX ID token to call APIs.

To generate a unique and temporary token for VTEX IO, run the following command:

$ vtex local token

The token will be automatically copied to the clipboard.

Learning more about a command

Use the --help flag as in the following to learn more about a specific command.

vtex [COMMAND] --help

Help CommandHelp Command

Did this page help you?