VTEX Developer Portal

VTEX IO CLI installation and command reference

VTEX IO CLI installation and command reference

Any development in VTEX IO begins and ends with the Toolbelt, our CLI (Command Line Interface).

Toolbelt allows you to login to a desired VTEX account, link your local files to the platform, manage an account's workspaces, in addition to performing any action necessary to your development process.

Installation

To install the VTEX IO’s CLI, you need to ensure that Node.js and Yarn are installed on your machine.

Thereafter, type yarn global add vtex in your computer’s terminal.

$ yarn global add vtex
To confirm that the installation occurred as expected, you can execute the vtex command. This should display all available commands in a help text.

Troubleshooting

After installing and running vtex in the terminal, an error saying that the command or program wasn't found may show up.

This happens due to an error concerning the Yarn installation. The yarn global add command does not properly add Yarn binaries to a directory known by your terminal as PATH.

By not adding the Yarn binaries to terminal PATH, Yarn and its programs can't be found, thereby resulting in an error when running Toolbelt.

Workaround for MacOS and Linux users

  1. In your local directories, find the Profile file. It is usually hidden and is named after the command line's interpreter. For example: If you're using bash, your Profile file will be named bashrc. If you use zsh, it will be zshrc;
  2. Once in the Profile file, add the following command: export PATH="$PATH: yarn global bin";
  3. Log in and log out of your terminal for the changes to take effect;
If your command line Shell is Fish, you can ignore the step by step above. Simply run the following command in your terminal: set -U fish_user_paths (yarn global bin) $fish_user_paths.

Workaround for Windows users

  1. Runs the yarn global bin command in your terminal. It will return the path in which the yarn global binaries were saved;
  2. Copy it to your clipboard. This path now must be added to the Windows Environment Variable Path;
  3. Click on the windows button and search for environment. Then, click on Edit the system environment variables;
  4. In the System Properties dialog, click on the Environment Variables... button;
  5. In User Variables, select Path and then click on the Edit... button;
  6. Click on the New button to add a new path to the search;
  7. Paste the yarn global binary path copied in step 2 and click OK when prompted. This will save your changes;
  8. Log in and log out of your terminal for the changes to take effect.

If the error persists, don't hesitate to send a ticket to our support team.

Command Reference

Every command executed in Toolbelt must begin with vtex, irrespective of its name, as can be seen in the examples in the command table below.

Command NameFunctionalityExample
addAdds an app to the dependencies of the app you are currently working on.vtex add [email protected]
browseOpens an endpoint in a browser window based on the current logged in account, workspace and environment data.vtex browse
deployPublishes an app as a stable version. It only works in apps already published as a release candidate version.vtex deploy [email protected]
deprecateDeprecates an app's version.vtex deprecate [email protected]
deps listLists the apps dependencies of the workspace in which you are working.vtex deps list
deps updateUpdates all app dependencies of the workspace in which you are working or a single app dependency (when specified).vtex deps update or vtex deps [email protected]
deps diffCompares app dependencies list of two workspaces and lists the apps that appear in both.vtex deps diff workspace1 workspace2
editionGets the edition of the account you are logged in.vtex edition
edition setSets an edition for the account you are logged in.vtex edition set [email protected]
initDisplays a list with boilerplate files or directories for new VTEX apps.vtex init
installInstalls an app to the account you are logged into.vtex install [email protected]
linkLocally links the app directory you are working into the development workspace you are working on.vtex link
listLists all VTEX apps running in the account you are logged into.vtex list
local accountDisplays the account name you are logged into and copies it to the clipboard.vtex local account
local workspaceDisplays the workspace name you are working in and copies it to the clipboard.vtex local workspace
local tokenDisplays the user's authentication token current being used and copies it to the clipboard.vtex local token
promotePromotes the production workspace you are working in to Master.vtex workspace promote
publishPublishes the app as a release candidate version.vtex publish [email protected] or vtex publish
redirects importAdds a URL redirect into the account and workspace you are logged into.vtex redirects import {fileName}.csv
redirects exportGets existing redirects from the account and workspace you are logged into.vtex redirects export {fileName}.csv
redirects deleteDeletes redirects in the the account and workspace you are logged into.vtex redirects delete {urlPath}
releaseOnly for git users. When executed in the app's directory, it releases the app's new version in the manifest.json file according to SemVer (semantic versioning) best practices, updates the CHANGELOG.md file, assigns commit tags and sends the performed changes to the app's repository.vtex release major beta
supportLogs you into an account using a support role.vtex support storecomponents
testRuns the app's unit tests according to the directory you are in (in case the app has any tests already configured for it).vtex test
undeprecateReverts an app's deprecation.vtex undeprecate [email protected]
uninstallUninstalls an app from the account you are logged into.vtex uninstall [email protected]
unlinkUnlinks the app directory you are in from the development workspace you are working in.vtex unlink
updateUpdate all installed apps to the latest version in the account you are logged into (valid only for patches and minors, Majors are not updated when using this command).vtex update
urlDisplays a complete URL in the terminal, based on the current logged in account, workspace and environment data.vtex url

Updated 7 days ago


VTEX IO CLI installation and command reference


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.