App Development

App Development

Accessing the list of commands

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

vtex help

{"base64":"  ","img":{"width":2206,"height":3054,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":842259,"url":""}}

See the Command Reference for more details.

Logging in to your VTEX account

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

vtex login {accountName}

Remember to replace the value in curly brackets with the values that apply to your scenario.

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

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

When you return to the computer terminal, you will have access to a development environment for this VTEX account. You will see some basic information about your account displayed as follows:

{"base64":"  ","img":{"width":2206,"height":864,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":203122,"url":""}}

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

Creating a new workspace

After logging in to a VTEX account, you will be automatically directed to the master workspace, 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 {workspaceName}

Notice that if a workspace with the chosen name already exists, you will be directed to it.

{"base64":"  ","img":{"width":2206,"height":586,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":131346,"url":""}}

Otherwise, you will be prompted to confirm whether you want to create a new workspace.

{"base64":"  ","img":{"width":2206,"height":586,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":123342,"url":""}}

From now on, all operations will be performed within the specified workspace.

Verifying your environment

To verify the account you are currently logged in to and the workspace you are using, run the following command:

vtex whoami

Installing an app

To install an app on your current account and workspace, use the following command:

vtex install {appVendor}.{appName}@{appVersion}

Remember to replace the values in curly brackets with the values that apply to your scenario.

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

{"base64":"  ","img":{"width":2206,"height":1072,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":227809,"url":""}}

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

Note that some apps are free, and others may have specific charging methods.

Starting a new project

To start a new project from pre-defined templates, you can run the following command:

vtex init

An error occurred while trying to load the image.

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

Developing locally

To develop locally, navigate to the directory of the app you are working on and run the following command to synchronize your local files with the VTEX platform.

vtex link

{"base64":"  ","img":{"width":2206,"height":1232,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":340494,"url":""}}

VTEX IO CLI will monitor your files and provide a URL related to that workspace. You will 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 can observe any local changes made to the linked files.

Checking the installed apps

To check apps installed on your account, you can run the following command:

vtex list

The installed apps are classified as follows:

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

Authenticating API requests

You can use the VTEX IO CLI to generate a unique and temporary user token, which can be helpful when running tests with VTEX APIs.

To generate a user token, run the following command:

vtex local token

The token will be automatically copied to the clipboard and can be used to authenticate requests for 24 hours. Learn more about user tokens.

The authentication of VTEX IO apps does not require this token. If you are developing VTEX IO apps, please refer to the App authentication guide.

Learning more about a command

Use the --help flag as shown below to learn more about a specific command.

vtex [COMMAND] --help

{"base64":"  ","img":{"width":2206,"height":1340,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":257798,"url":""}}

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page