📝 Table of Contents
Introduction
- What is zcli?
Getting Started with zcli
- Installing zcli
- Adding a Profile
- Creating Starter Files for a New Zendesk App
- Testing the App Locally
- Deploying the App to Your Zendesk Instance
- Updating an App in Your Zendesk Instance
Limitations of zcli
- Current Limitations
- Possible Workarounds
Advanced Topics and Commands
- Future Features
- Suggestions for Future Topics
Conclusion
📝 Introduction
Are you looking for a more efficient way to build and manage your Zendesk apps? Look no further than zcli, the command line interface built specifically for Zendesk app developers. In this article, we'll explore what zcli is, how to get started with it, and some of its current limitations. We'll also cover how to create a new Zendesk app using zcli, test it locally, and deploy it to your Zendesk instance. Finally, we'll discuss how to update an app that has already been installed in your Zendesk instance.
What is zcli?
Zcli is a command line interface that helps you build and manage your Zendesk apps. With zcli, you can create new apps, upload them directly to your Zendesk instance, and update the apps as needed directly from the terminal. Zcli is built with Node.js using the OpenCLI framework, which results in a much smoother developer experience and native Windows support. This means no more installing Linux on Windows machines to run the previous Zendesk apps tools, as well as full compatibility with M1 Max.
📝 Getting Started with zcli
Installing zcli
To get started with zcli, you'll need to install it on your computer. Node v12 or above is required, so you can check your node version by running `node -v` in the terminal. If your version is below v12, you can update it by using Node Version Manager or by heading to the Node website to download the necessary updates.
Next, you can go ahead and install zcli by running the `npm install @zendesk/zcli -g` command in the terminal. You can confirm the installation version by running `zcli -v`.
Adding a Profile
A profile in zcli corresponds to your login credentials in Zendesk, and zcli supports one profile per subdomain. You'll be prompted to enter your email address, password, and your Zendesk instance subdomain. If you've disabled password access, you can use an API token instead using the `email/token` format.
Creating Starter Files for a New Zendesk App
Similar to the Zendesk apps tools, there are a few different ways to generate starter files for your app. For the purposes of this article, we'll stick to the basic apps data files. To begin, we'll `cd` into the desktop as that's where we'll want the app directory to live. Next, we'll run the `zcli apps new` command. The first prompt you'll see is to enter a directory name for the app files. If you have one created already, you can enter that here. Otherwise, you can enter a new folder name which will be created to store the app. We'll go ahead and create a new directory called `ccli-example`. Next, we'll be prompted to enter the app author's name, email address, and a name for the app. We'll see in a minute where these details can be updated, but for now, these can be whatever you like. You should see a success message letting you know the project has been created. Let's go ahead and `cd` into the project directory and open the files in VS Code.
Testing the App Locally
Using zcli, we can start a local web server to run a Zendesk app on your computer. This makes building and testing a breeze since you don't need a package upload and install each time you make changes while developing your app. To spin up the server, we'll run the `zcli apps server` command in the terminal. After a couple of seconds, you'll see the app server is now running on `localhost:4567`. Next up, we'll need to append `zcli_apps=true` to the end of our Zendesk instance URL, similarly to how you might have done in the past. Since the app is specified as a ticket sidebar app by default, let's head over to a ticket and do that now.
Deploying the App to Your Zendesk Instance
Once your app has been tested and is ready to be deployed, the next steps are validating and packaging the app and uploading and installing the app to your Zendesk instance. This is accomplished using one simple command, the `zcli apps create` command. In the terminal, let's run the `zcli apps create` command, which will begin the process of validating, packaging, and uploading the app to your Zendesk instance. If you run into any errors during the installation process, you'll just need to update the app as outlined in the error message and run the `zcli apps create` command again.
Updating an App in Your Zendesk Instance
So you've installed an app in your Zendesk instance, and since then, you've made some changes and improvements that you'd like to push to update the app. Again, with the use of just one simple command, we can push the changes live to your Zendesk instance. We do this using the `zcli apps update` command.
📝 Limitations of zcli
Current Limitations
Since zcli is currently in open beta, there will be some limitations to using zcli as we work towards general availability. Zendesk Guide local theme preview, for example, is not currently supported when using zcli at this time. If you're using Guide local theme preview to build custom themes for your Zendesk Help Center, you should continue to use the Zendesk apps tools. Another limitation is if you're running Linux on Windows using WSL, some commands will fail unless you're using a version of WSL with support for graphical user interface apps with X11.
Possible Workarounds
We've provided possible workarounds for the current limitations of zcli in our documentation, which we'll link below. Be sure to check it out if you're running into any issues.
📝 Advanced Topics and Commands
Future Features
While zcli is currently in open beta, we'll be continuing to work on bringing more features, such as Guide theme preview, to zcli in the future. Watch this space for updates!
Suggestions for Future Topics
While we've covered the basics you need to get started, there are a few more advanced topics and commands we'll be discussing in future articles. If there's any topic you'd be interested in us covering in the future, be sure to leave a comment below.
📝 Conclusion
In conclusion, zcli is a powerful tool for building and managing your Zendesk apps. With its smooth developer experience and native Windows support, it's a great choice for developers looking to streamline their workflow. We hope this article has been helpful in getting you started with zcli, and we look forward to seeing what you create with it!
🔍 Highlights
- Zcli is a command line interface that helps you build and manage your Zendesk apps.
- With zcli, you can create new apps, upload them directly to your Zendesk instance, and update the apps as needed directly from the terminal.
- Zcli is built with Node.js using the OpenCLI framework, which results in a much smoother developer experience and native Windows support.
- To get started with zcli, you'll need to install it on your computer and add a profile.
- Once your app has been tested and is ready to be deployed, the next steps are validating and packaging the app and uploading and installing the app to your Zendesk instance.
- Zcli is currently in open beta, and there are some limitations to using zcli as we work towards general availability.
- We've provided possible workarounds for the current limitations of zcli in our documentation.
- While zcli is currently in open beta, we'll be continuing to work on bringing more features, such as Guide theme preview, to zcli in the future.
❓ FAQ
Q: What is zcli?
A: Zcli is a command line interface that helps you build and manage your Zendesk apps.
Q: What are the current limitations of zcli?
A: Zendesk Guide local theme preview is not currently supported when using zcli at this time. If you're using Guide local theme preview to build custom themes for your Zendesk Help Center, you should continue to use the Zendesk apps tools. Another limitation is if you're running Linux on Windows using WSL, some commands will fail unless you're using a version of WSL with support for graphical user interface apps with X11.
Q: How do I install zcli?
A: To install zcli, you'll need to have Node v12 or above installed on your computer. You can then run the `npm install @zendesk/zcli -g` command in the terminal to install zcli.
Q: How do I create a new Zendesk app using zcli?
A: To create a new Zendesk app using zcli, you'll need to run the `zcli apps new` command in the terminal. You'll be prompted to enter a directory name for the app files, as well as the app author's name, email address, and a name for the app.
Q: How do I test my app locally using zcli?
A: To test your app locally using zcli, you can start a local web server by running the `zcli apps server` command in the terminal. You'll also need to append `zcli_apps=true` to the end of your Zendesk instance URL.
Q: How do I deploy my app to my Zendesk instance using zcli?
A: To deploy your app to your Zendesk instance using zcli, you'll need to run the `zcli apps create` command in the terminal. This will begin the process of validating, packaging, and uploading the app to your Zendesk instance.
Q: How do I update an app that has already been installed in my Zendesk instance using zcli?
A: To update an app that has already been installed in your Zendesk instance using zcli, you'll need to run the `zcli apps update` command in the terminal.
