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.

Before you start

To install ZCLI, you'll need the following:

• Node.js 14.17.3 or later

• 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

You install ZCLI as a Node.js package.

To install ZCLI

1. In your computer's terminal, run:

                  
   
                   
   npminstall@zendesk/zcli -g
                  

2. Verify ZCLI is installed and ready for use:

                  
   
                   
   zclihelp
                  

   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 theZCLI documentation on GitHub.

App configuration file

Zendesk apps support an optionalzcli.apps.config.json文件在应用程序的根目录。You can use the file to:

• Store an app id. This id is unique within a Zendesk instance.
• Definetest installation settings

Note:If you previously used ZAT,zcli.apps.config.jsonreplaces the.zatandsettings.ymlfiles.

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:

• Profiles
• Environment variables

Important:如果你是一个Windows用户使用Windows Subsystem for Linux (WSL), useenvironment 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 password. If you're using an API token, append "/token" to your email address, and enter your API token as the password.

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 thezcli login -icommand 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:

             

              
zclilogout
             

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.

Important:If you're using API token authentication, don't append "/token" to theZENDESK_EMAILvalue. ZCLI appends this suffix for you.

For security reasons, basic authentication isn't recommended. Depending on your setup, theZENDESK_PASSWORDvariable may store your Zendesk password in plaintext.

验证ZCLI使用环境变量

The steps for authenticating ZCLI using environment variables vary based on your preferred authentication scheme, OS, and environment.

To authenticate ZCLI using environment variables

1. Set theZENDESK_SUBDOMAINvariable 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
                  

2. Set the other environment variables required for your preferred authentication scheme.

   For example, to use API token authentication, set theZENDESK_EMAILvariable to your email address and theZENDESK_API_TOKENvariable to your Zendesk API token.

   macOS

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

   Windows

                  
   
                   
   setx ZENDESK_EMAIL "{email}"setx ZENDESK_API_TOKEN "{api_token}"
                  

   Linux

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

3. Reload your terminal's shell.

   macOS

                  
   
                   
   source~/.zshrc
                  

   Windows

   Close and reopen your terminal.

   Linux

                  
   
                   
   source ~/.bashrc
                  

4. As an optional step, print each environment variable's value to ensure it's set.

   macOS and Linux

   Runprintenv {var_key}. Replace{var_key}with the environment variable's key. Example:

                  
   
                   
   printenv ZENDESK_SUBDOMAIN
                  

   Windows

   Runecho %{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:

1. OAuth 2.0 access token
2. API token
3. Basic authentication

For example, if you specify theZENDESK_SUBDOMAIN,ZENDESK_OAUTH_TOKEN,ZENDESK_EMAIL, andZENDESK_API_TOKENvariables, ZCLI will only attempt OAuth authentication using theZENDESK_SUBDOMAINandZENDESK_OAUTH_TOKENvariables. If theZENDESK_OAUTH_TOKENvariable contains an invalid OAuth 2.0 access token, authentication fails. ZCLI won't attempt API token authentication using theZENDESK_EMAILorZENDESK_API_TOKENvariables.

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项目s
                  

2. To create basic app starter files, run:

                  
   
                   
   zcli apps:new
                  

   Alternatively, use the--scaffold=reactoption to use the亚博Zendesk反应应用脚手架.

                  
   
                   
   zcli apps:new --scaffold=react
                  

3. 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 therequired 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 toZCLI server limitations.

1. If your app includesinstallation settings, specify test setting values in thezcli.apps.config.jsonfile as an optional first step. SeeDefining test settings.

   If you don't specify setting values inzcli.apps.config.json, ZCLI prompts you for the values when you start the ZCLI server.

   If you previously used ZAT,zcli.apps.config.jsonreplaces thesettings.ymlfile. The ZCLI server doesn't read setting values fromsettings.ymlordefaultsetting values frommanifest.json.

2. 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 inzcli.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.

3. 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.

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

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

                  
   
                   
   https://{subdomain}.亚博.com/agent/tickets/{123}
                  

5. Append?zcli_apps=trueto the URL, and reload the page.

   For example:

                  
   
                   
   https://{subdomain}.亚博.com/agent/tickets/{123}?zcli_apps=true
                  

6. 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 theAppsicon. This opens theAppstray.

   

   If your app doesn't appear in theAppstray, click theRefreshicon 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 thezcli apps:servercommand's--portflag. Example:

             

              
zcli apps:server --port=4254
             

To preview the app, append?zcli_apps={port}to the Zendesk URL. Example:

             

              
https://{subdomain}.亚博.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 fromrequirements.json. Similarly, you can't access therequirementobject using the ZCLI server.

• Event notifications from theSend Notification to Appendpoint.

As a workaround, you can use ZCLI to package, upload, and update the app. SeePackaging and installing a private Zendesk appandUpdating 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 thezcli apps:createcommand instead. The command packages and installs the app as a private app in your Zendesk instance. Once installed, you can use ZCLI toupdate the appand 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 atmpfolder 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 thetmpfolder.

• Creates azcli.apps.config.jsonfile 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 thezcli apps:updatecommand to update a private app. The command requires azcli.apps.config.json文件在应用程序的根目录。该文件必须有限公司ntain a validapp_idproperty.

1. If it doesn't already exist, create azcli.apps.config.json文件在应用程序的根目录。

   If you previously usedzcli apps:create, the command creates azcli.apps.config.jsonthat contains theapp_id. Skip to step 4.

2. To get theapp_idvalue, 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_idfor your app on the response.

3. Inzcli.apps.config.json, add theapp_idas 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 toCreate brand app assetsandCreate 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 atmpfolder in the app's root directory.

2. To submit the ZIP file as a public app to the Zendesk Marketplace, refer toSubmit your app.

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

Limitations

• The ZCLI server can't receive event notifications from theSend Notification to Appendpoint. As a workaround, you can use ZCLI to install the app as a private app instead. SeePackaging and installing a private Zendesk app. Alternatively, you can use ZAT'slocal web serverand set the Send Notification to App request'sapp_idparameter to0.