Using ZCLI
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.
Developing Zendesk apps without some local testing tools is possible but not easy. For example, each time you want to test a change, you have to package and upload the app and then install and run it remotely in Zendesk Support. To get around this problem, you can use ZCLI. Among other tasks, ZCLI lets you do the following:
- Automatically create all the necessary files and folders for a new app
- Test your app locally in a browser
- Validate your app
- Package your app for upload
Before you start
To install ZCLI, you'll need the following:
-
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
- Debian/Ubuntu:
Installing and updating ZCLI
You install ZCLI as a Node.js package.
To install ZCLI
-
In your computer's terminal, run:
npm install @zendesk/zcli -g
-
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:
- Store an app id. This id is unique within a Zendesk instance.
- Define test installation settings
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're a Windows user using the Windows Subsystem for Linux (WSL), use environment variables. To manage profiles in Linux environments, ZCLI requires X11. X11 isn't supported on most Windows machines, even with WSL.
Profiles
Each ZCLI profile is associated with a Zendesk subdomain. To add a profile, run:
zcli login -i
When prompted, enter your subdomain, email address, and your API token.
Note: You don't need to append "/token" to your email address. ZCLI appends this suffix for you.
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
You can also authenticate ZCLI with Zendesk using environment variables. This lets you use ZCLI in a continuous integration and continuous deployment (CI/CD) pipeline. It's also helpful if your development environment doesn't support ZCLI profiles.
Supported authentication schemes
ZCLI supports the following environment variables and associated authentication schemes.
Authentication scheme | Required environment variables |
---|---|
OAuth 2.0 access token | ZENDESK_SUBDOMAIN , ZENDESK_OAUTH_TOKEN |
API token | ZENDESK_SUBDOMAIN , ZENDESK_EMAIL , ZENDESK_API_TOKEN |
Important considerations
- If you're using API token authentication, don't append "/token"
to the ZENDESK_EMAIL
value. ZCLI appends this suffix for you.
- Environmental variables aren't supported when authenticating theme-related commands. For more information, see Previewing theme changes locally.
Authenticating ZCLI using environment variables
The steps for authenticating ZCLI using environment variables vary based on your preferred authentication scheme, OS, and environment.
To authenticate ZCLI using environment variables
-
Set the
ZENDESK_SUBDOMAIN
variable to your Zendesk account's subdomain.macOS
echo 'export ZENDESK_SUBDOMAIN="{subdomain}"' >> ~/.zshrc
Windows
setx ZENDESK_SUBDOMAIN "{subdomain}"
Linux
echo 'export ZENDESK_SUBDOMAIN="{subdomain}"' >> ~/.bashrc
-
Set the other environment variables required for your preferred authentication scheme.
For example, to use API token authentication, set the
ZENDESK_EMAIL
variable to your email address and theZENDESK_API_TOKEN
variable to your Zendesk API token.macOS
echo 'export ZENDESK_EMAIL="{email}"' >> ~/.zshrc
echo 'export ZENDESK_API_TOKEN="{api_token}"' >> ~/.zshrc
Windows
setx ZENDESK_EMAIL "{email}"
setx ZENDESK_API_TOKEN "{api_token}"
Linux
echo 'export ZENDESK_EMAIL="{email}"' >> ~/.bashrc
echo 'export ZENDESK_API_TOKEN="{api_token}"' >> ~/.bashrc
-
Reload your terminal's shell.
macOS
source ~/.zshrc
Windows
Close and reopen your terminal.
Linux
source ~/.bashrc
-
As an optional step, print each environment variable's value to ensure it's set.
macOS and Linux
Run
printenv {var_key}
. Replace{var_key}
with the environment variable's key. Example:printenv ZENDESK_SUBDOMAIN
Windows
Run
echo %{var_key}%
. Replace{var_key}
with the environment variable's key. Example:echo %ZENDESK_SUBDOMAIN%
Order of precedence
You can only authenticate ZCLI using one authentication method or scheme at a time. If you use both ZCLI environment variables and ZCLI profiles, ZCLI only uses the environment variables for authentication.
If you specify environment variables for multiple authentication schemes, ZCLI uses the following order of precedence:
- OAuth 2.0 access token
- API token
For example, if you specify the ZENDESK_SUBDOMAIN
, ZENDESK_OAUTH_TOKEN
,
ZENDESK_EMAIL
, and ZENDESK_API_TOKEN
variables, ZCLI will only attempt OAuth
authentication using the ZENDESK_SUBDOMAIN
and ZENDESK_OAUTH_TOKEN
variables. If the ZENDESK_OAUTH_TOKEN
variable contains an invalid OAuth 2.0
access token, authentication fails. ZCLI won't attempt API token authentication
using the ZENDESK_EMAIL
or ZENDESK_API_TOKEN
variables.
Creating starter files for a Zendesk app
Use ZCLI to create starter files for a new Zendesk app.
-
In your shell, navigate to the directory you'll use to store the app. For example:
cd projects
-
To create basic app starter files, run:
zcli apps:new
Alternatively, use the
--scaffold=react
option to use the Zendesk React app scaffold.zcli apps:new --scaffold=react
-
At the prompts, enter:
- The app's directory name
- Your name
- Your email address
- Your website URL (optional)
- 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.
The ZCLI server doesn't support some Zendesk Apps framework (ZAF) features. Refer to ZCLI server limitations.
-
If your app includes installation settings, specify test setting values in the zcli.apps.config.json file as an optional first step. See Defining test settings.
If you don't specify setting values in zcli.apps.config.json, ZCLI prompts you for the values when you start the ZCLI server.
If you previously used ZAT, zcli.apps.config.json replaces the settings.yml file. The ZCLI server doesn't read setting values from settings.yml or default setting values from manifest.json.
-
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.If your app includes an installation setting without a default value in zcli.apps.config.json, ZCLI interactively prompts you for the value.
After a moment, a status message appears informing you that the server has started.
Note: To stop the server, press Ctrl+C.
-
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.
-
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}
-
Append
?zcli_apps=true
to the URL, and reload the page.For example:
https://{subdomain}.zendesk.com/agent/tickets/{123}?zcli_apps=true
-
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.
Using a custom port
By default, the ZCLI server runs on port 4567. To run the server on another
port, use the zcli apps:server
command's --port
flag. Example:
zcli apps:server --port=4254
To preview the app, append ?zcli_apps={port}
to the Zendesk URL. Example:
https://{subdomain}.zendesk.com/agent/tickets/123?zcli_apps=4254
ZCLI server limitations
The ZCLI server doesn't support the following ZAF features:
-
Secure settings. The ZCLI server won't render secure settings.
-
App requirements. The ZCLI server can't create resources from requirements.json. Similarly, you can't access the requirement object using the ZCLI server.
-
Event notifications from the Send Notification to App endpoint.
As a workaround, you can use ZCLI to package, upload, and update the app. See 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.
-
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 theapp_id
. Skip to step 4. -
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 theapp_id
for your app on the response. - Support:
-
In zcli.apps.config.json, add the
app_id
as a property of the root-level JSON object. Example:{
"app_id": 1234
}
-
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 app assets and Create content.
-
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.
-
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
- The ZCLI server can't receive event notifications from the Send Notification
to App
endpoint. As a workaround, you can use ZCLI to install the app as a private
app instead. See Packaging and installing a private Zendesk
app. Alternatively, you can use
ZAT's local web
server
and set the Send Notification to App request's
app_id
parameter to0
.