Note: The Zendesk Command Line Interface (ZCLI) is in open beta. It is fully supported by Zendesk but may change at any time.

ZCLI is a command-line tool for developing Zendesk apps. You can use ZCLI to build, test, and package your Zendesk apps locally. ZCLI replaces the Zendesk App Tools (ZAT), which are in maintenance mode.

Before you start

  • Before you install ZCLI, complete the Setting up your development environment tutorial.

  • If you're using Linux, depending on your distribution, you'll need to run:

    • Debian/Ubuntu: sudo apt install libsecret-1-dev
    • Red Hat-based: sudo yum install libsecret-devel
    • Arch Linux: sudo pacman -S libsecret

Installing and updating ZCLI

To install ZCLI:

  1. Check your Node.js version:

    node -v

    ZCLI requires Node.js 14.17.3 or above. If needed, use nvm to install and use a compatible Node.js version. For example:

    nvm install 14.17.3nvm use 14.17.3
  2. Verify npm is installed and ready for use:

    npm -v

    The command returns your installed npm version.

  3. Install ZCLI:

    npm install @zendesk/zcli -g
  4. Verify ZCLI is installed and ready for use:

    zcli help

    The command returns your installed ZCLI version and other help information.

To update ZCLI, run the installation command again. ZCLI warns you if your installed version is out of date.

Commands

This article covers the most common ZCLI commands. For the full list of commands, refer to the ZCLI documentation on GitHub.

App configuration file

Zendesk apps support an optional zcli.apps.config.json file in the app's root directory. You can use the file to:

Note: If you previously used ZAT, zcli.apps.config.json replaces the .zat and settings.yml files.

Authentication

The following ZCLI commands require authentication with Zendesk:

  • apps:create
  • apps:package
  • apps:update
  • apps:validate

You can authenticate ZCLI using one of the following methods:

Important: If you use the Ubuntu terminal environment for Windows, use environment variables. To manage profiles, ZCLI requires X11, a windowing system for Linux and macOS. X11 isn't supported on most Windows machines, even in the Ubuntu terminal environment.

Profiles

Each ZCLI profile is associated with a Zendesk subdomain. To add a profile, run:

zcli login -i

When prompted, enter your subdomain, email, and password. If you've disabled password access for your account, use an API token instead. When providing an API token, the username must be in the [email protected]/token format.

The login command creates a profile for the subdomain you entered. ZCLI saves your credentials securely in the keystore of your operating system (OS).

Updating a profile

ZCLI supports one profile per subdomain. To change the credentials for a subdomain, run the zcli login -i command again. When prompted, enter your new credentials.

Switching profiles

To get a list of available profiles, run:

zcli profiles:list

The command returns a list of available profiles by subdomain, including the active profile.

To switch the active profile, run:

zcli profiles:use {subdomain}

Replace {subdomain} with a subdomain from the list.

Removing a profile

To remove the active profile, run:

zcli logout

When you remove a profile, it also removes the related authentication credentials.

To remove a profile other than the active profile, run:

zcli profiles:remove {subdomain}

Replace {subdomain} with the subdomain for the profile.

Environment variables

To use environment variables to authenticate ZCLI with Zendesk, follow these steps:

  1. In your shell, set the ZENDESK_SUBDOMAIN variable to your Zendesk account's subdomain.

    On macOS:

    echo 'export ZENDESK_SUBDOMAIN="{subdomain}"' >> ~/.zshrc

    In the Ubuntu terminal environment for Windows:

    echo 'export ZENDESK_SUBDOMAIN="{subdomain}"' >> ~/.bashrc
  2. Set the ZENDESK_EMAIL variable to your email address.

    On macOS:

    echo 'export ZENDESK_EMAIL="{email}"' >> ~/.zshrc

    In the Ubuntu terminal environment for Windows:

    echo 'export ZENDESK_EMAIL="{email}"' >> ~/.bashrc
  3. Set the ZENDESK_API_TOKEN variable to your Zendesk API token. To get this token, see Generating a new API token in Zendesk help.

    On macOS:

    echo 'export ZENDESK_API_TOKEN="{api_token}"' >> ~/.zshrc

    In the Ubuntu terminal environment for Windows:

    echo 'export ZENDESK_API_TOKEN="{api_token}"' >> ~/.bashrc

    Instead of ZENDESK_API_TOKEN, you can set the ZENDESK_PASSWORD variable to your Zendesk password. However, this stores your password as plaintext and isn't recommended for security reasons.

    On macOS:

    echo 'export ZENDESK_PASSWORD="{password}"' >> ~/.zshrc

    In the Ubuntu terminal environment for Windows:

    echo 'export ZENDESK_PASSWORD="{password}"' >> ~/.bashrc
  4. Reload your shell.

    On macOS:

    source ~/.zshrc

    In the Ubuntu terminal environment for Windows:

    source ~/.bashrc

To display your current environment variables and their values, run printenv. To the value of a specific environment variable, run printenv {var_key}. Replace {var_key} with the environment variable's key. Example:

printenv ZENDESK_SUBDOMAIN

Creating starter files for a Zendesk app

Use ZCLI to create starter files for a new Zendesk app.

  1. In your shell, navigate to the directory you'll use to store the app. For example:

    cd projects
  2. To create basic app starter files, run:

    zcli apps:new

    Alternatively, use the --scaffold=react option to use the Zendesk app scaffold.

    zcli apps:new --scaffold=react
  3. At the prompts, enter:

    • The app's directory name
    • Your name
    • Your email address
    • The app's name

    ZCLI creates app starter files in the directory you entered. If you used basic starter files, the directory includes the required files for a Zendesk app.

Testing your Zendesk app locally

You can use ZCLI to start a local web server that lets you run a Zendesk app on your computer. You don't need to package, upload, or install the app first. This is useful if you want to test or preview an app as you make changes.

Note: The ZCLI server doesn't support some Zendesk Apps framework (ZAF) features. Refer to ZCLI server limitations.

  1. To start a ZCLI server for an app, run:

    zcli apps:server {app_directory}

    Replace {app_directory} with a relative path to the app's root directory. If your shell is already in the app's root directory, omit this parameter.

    After a moment, a status message appears informing you that the server has started.

    Note: To stop the server, press Ctrl+C.

  2. Open an incognito or private window in your browser. We recommend Chrome or Firefox. Safari doesn't support the ZCLI web server.

    An incognito or private window doesn't cache files used by the app. Cached files may prevent the browser from displaying the app's latest changes.

  3. Sign in to Zendesk and navigate to the URL that displays your app. This URL varies based on the app location.

    For example, you can view apps in the Support ticket sidebar from any ticket URL:

    https://{subdomain}.zendesk.com/agent/tickets/{123}
  4. Append ?zcli_apps=true to the URL, and reload the page.

    For example:

    https://{subdomain}.zendesk.com/agent/tickets/{123}?zcli_apps=true
  5. Depending on the app location, you may need to take some additional steps to display the app.

    For example, to display an app in the ticket sidebar, click the Apps icon. This opens the Apps tray.

    If your app doesn't appear in the Apps tray, click the Refresh icon to reload your apps.

ZCLI server limitations

The ZCLI server doesn't support the following ZAF features:

  • Secure settings. The ZCLI server won't render secure settings.

  • Requirements. The ZCLI server doesn't install requirements from the requirements.json file. The Core Apps API's requirement property won't work either.

As a workaround, you can use ZCLI to package, upload, and update the app. Refer to Packaging and installing a private Zendesk app and Updating a private Zendesk app.

Packaging and installing a private Zendesk app

The ZCLI server doesn't support some ZAF features. To preview an app that uses these features, use the zcli apps:create command instead. The command packages and installs the app as a private app in your Zendesk instance. Once installed, you can use ZCLI to update the app and test changes.

To use the command, run:

zcli apps:create {app_directory}

Replace {app_directory} with a relative path to the app's root directory. If your shell is already in the app's root directory, omit this parameter.

The command:

  • Runs validation tests on the app's files. If the tests detect a problem, the command stops and returns an error message.

  • Packages the app's files into a ZIP file. ZCLI saves the ZIP file in a tmp folder in the app's root directory.

  • Uploads and installs the ZIP file as a private app to the Zendesk instance. If you're using profiles, this is the active profile's instance. If successful, ZCLI then deletes the ZIP file from the tmp folder.

  • Creates a zcli.apps.config.json file in the local app directory. This file contains the app ID. This ID is unique within the Zendesk instance. If you're using profiles, this is the active profile's instance.

Updating a private Zendesk app

You can use the zcli apps:update command to update a private app. The command requires a zcli.apps.config.json file in the app's root directory. The file must contain a valid app_id property.

  1. If it doesn't already exist, create a zcli.apps.config.json file in the app's root directory.

    If you previously used zcli apps:create, the command creates a zcli.apps.config.json that contains the app_id. Skip to step 4.

  2. To get the app_id value, sign in to the Zendesk product for the app as an admin. Then open the respective page for the product in the same browser:

    • Support: https://{subdomain}.zendesk.com/api/support/apps/installations.json
    • Chat: https://{subdomain}.zendesk.com/api/chat/apps/installations.json
    • Sell: https://{subdomain}.zendesk.com/api/sell/apps/installations.json

    Replace {subdomain} with your Zendesk subdomain. Find the app_id for your app on the response.

  3. In zcli.apps.config.json, add the app_id as a property of the root-level JSON object. Example:

    {  "app_id": 1234}
  4. Run:

    zcli apps:update {app_directory}

    Replace {app_directory} with a relative path to the app's root directory. If your shell is already in the app's root directory, omit this parameter.

    After running the command, refresh your app to preview the changes.

Packaging a Zendesk app for manual upload

When your app is done, you can package it into a ZIP file. You can then submit the ZIP file to the Zendesk Marketplace as a public app. You can also manually upload the ZIP file to a Zendesk instance as a private app.

Tip: The Zendesk Marketplace has additional requirements for public apps. Refer to Create brand assets and Create content.

  1. To package the app, run:

    zcli apps:package {app_directory}

    Replace {app_directory} with a relative path to the app's root directory. If your shell is already in the app's root directory, omit this parameter.

    The command:

    • Runs validation tests on the app's files. If the tests detect a problem, the command stops and returns an error message.
    • Packages the app's files into a ZIP file. ZCLI saves the ZIP file in a tmp folder in the app's root directory.
  2. To submit the ZIP file as a public app to the Zendesk Marketplace, refer to Submit your app.

    To upload and install the ZIP file as a private app, refer to Uploading and installing a private app.

Limitations

ZCLI doesn't support previews for Zendesk Guide themes. To preview Guide themes, use ZAT's theme preview command. Refer to the ZAT command documentation.