ZAT commands

Using the Zendesk Apps Tools (ZAT)

Note: ZAT is in maintenance mode. For the best experience, use the Zendesk Command Line Interface (ZCLI) to develop Zendesk apps.

ZAT is a collection of command-line tools that simplify building and deploying Zendesk apps. The tools let you create, test, validate, and package your apps locally.

$ zat create

Available commands for building apps:

• new
• validate
• server
• create
• update
• package
• clean

ZAT also includes a command for previewing changes to Zendesk Guide themes locally.

• theme preview

Installing and updating ZAT

To install the tools, see Installing and using ZAT. See the known issues if you run into any problems installing or using the tools.

To update your tools to the latest version, run $ gem update zendesk_apps_tools.

Authentication

The following commands need access to your Zendesk account: create, update, and theme. Each command prompts you for your subdomain, username, and API token. The username must be in the format [email protected]/token. See API token in the REST API docs.

ZAT saves the subdomain and username in a file named .zat in the local folder so you don't have to enter them again the next time you run the command. Example:

{
  "subdomain": "your_subdomain",
  "username": "your_username"
}

Optionally, you can include a password parameter in your .zat file so you are not prompted for this every time you run the create, update or theme command. Example:

{
  "subdomain": "your_subdomain",
  "username": "your_username/token",
  "password": "api_token"
}

Note: If you use the password parameter in the .zat file, it will be stored as plain text. Use this parameter with caution. If you are using source control, we recommend adding .zat to your .gitignore file.

If you use an API token, .zat file should look similar to:

{
  "subdomain": "your_subdomain",
  "username": "[email protected]/token",
  "password": "[TOKEN]"
}

If you make a mistake typing your subdomain, username, or password the first time you run the command, change the values in the .zat file.

Note: Files with a leading period are hidden by default in macOS. See Show Hidden Files on Mac OS X on osxdaily.com.

new

Creates all the files necessary to start building a Zendesk app. Use the --scaffold option to download and use the Zendesk React app scaffold as the base of your app. For more instructions on using the React app scaffold, see the readme.

$ zat new

$ zat new --scaffold

validate

Runs a suite of validation tests against your app. Because the same tests are run when you upload the app, you probably won't be able to upload the app until your app passes the validate tests.

$ zat validate

server

Starts a local HTTP server that lets you run and test your apps locally.

$ zat server

Run the command in the app's local root folder. Switch to the product interface and append ?zat=true to the page URL.

Because the app runs locally in an iframe in the Zendesk page, your browser may block it as mixed content. Firefox doesn't block this content but Safari does and has no option to disable blocking. Chrome blocks it by default but you can unblock it. Click the lock icon on the left side of the address bar, select Site Settings > Privacy and Security, then select the Allow option under Insecure content.

To serve apps on custom ports, run the command zat server --port 4254. Then, load each app by switching to the product interface and append ?zat=4254 to the appropriate port number.

For details, refer to Testing your app locally in a browser.

You can also test apps with secure settings or requirements locally. Refer to Packaging and installing a private Zendesk app and Updating a private Zendesk app.

To stop the server, switch to your command-line interface and press Control+C.

create

Packages, uploads, and installs the app into the Zendesk products specified in the app manifest.

$ zat create

The create command performs the following actions:

• Packages the app's files into a zip file and saves it in a local folder named tmp
• After prompting you for a subdomain, username, and password, uploads and installs the package into the Zendesk products specified in the app's manifest file
• After uploading the app, saves the app ID and other metadata in a file named .zat in the local folder

The command prompts you for a subdomain, username, and password. See Authentication.

Requirements

• API access is enabled in the Admin Center interface (Apps and integrations > APIs > Zendesk APIs)
• ZAT v2.0 or later for installing. All versions for packaging and uploading. Run zat -v to get your version

Options

The create command has the following options:

• no-install - Prevents the app from installing in the product instance. The app will still be uploaded and appear in the "Not Installed Apps" section of the Private Apps tab in the admin interface. Example:

  zat create --no-install

• path - Specifies a folder containing the app files to package and upload. Example:

  zat create --path=./dev/zendesk_app

• zipfile - Specifies a folder containing a packaged zip file. Use this option if you used package to package the app and you want to upload and install it. Example:

  zat create --zipfile=~/my_app/tmp/app-2017033340.zip

update

Updates an existing private app in the Zendesk products specified in the app's manifest file.

$ zat update

The command packages the app's files and uploads the package.

The command prompts you for a subdomain, username, and password. See Authentication.

Requirement

• API access is enabled in the Zendesk Support admin interface (Admin > Channels > API).

Options

The update command has the following options:

• path - Specifies a folder containing the app files to package and upload. Example:

  zat update --path=./dev/zendesk_app

• zipfile - Specifies a folder containing a packaged zip file. Use this option if you used package to package the updated app and you want to upload and install it. Example:

  zat update --zipfile=~/my_app/tmp/app-2017033340.zip

If you didn't use create to upload the app initially (for example, if you uploaded the file using the product admin interface), you must create a file named .zat with the following content in the app's local root directory:

{
  "subdomain": "your_subdomain",
  "username": "your_username",
  "app_id": 1234
}

Note: The create command creates this file for you.

The username value is the email address you use to sign in.

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

For details, refer to Updating a private Zendesk app.

package

Creates a zip file that you can upload and install in a Zendesk account.

$ zat package

The command saves the zip file in a folder named tmp.

You can upload and install the app from the product admin interface or from the command line using the create command with the zipfile option.

clean

Removes the zip files in the tmp folder that's created when you package the app.

$ zat clean

theme preview

Starts a local HTTP server to preview a Zendesk Guide theme locally while you make changes to it. This feature is available only on the Zendesk Suite Professional plan or above.

$ zat theme preview

For details, see Previewing theme changes locally in the Guide documentation.

The command prompts you for a subdomain, username, and password. See Authentication.