🎫 Zendesk CLI Helper

A powerful command-line interface for Zendesk ticket management. Streamline your customer support workflow with easy-to-use commands for listing and creating tickets.

✨ Features

• 📋 Ticket listing with status filtering
• 🎫 Ticket creation with subject, description, and priority
• 🎨 Pretty output with JSON formatting (jq/python3)
• 🔧 Flexible configuration with multiple config file locations
• ⚡ Zsh completion with smart tab completion
• 🔒 Secure authentication via API tokens

🚦 Quick Start

One-line Installation

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/zendesk-cli/main/install.sh | bash

Manual Installation

1. Download and install:

   git clone https://github.com/jeromecoloma/zendesk-cli.git
   cd zendesk-cli
   chmod +x install.sh
   ./install.sh

2. Restart your shell or run:

   source ~/.zshrc

3. Initialize configuration (optional):

   zendesk-cli init

Update

To update to the latest version:

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/zendesk-cli/main/install.sh | bash -s -- --update

Uninstallation

To remove zendesk-cli completely:

curl -fsSL https://raw.githubusercontent.com/jeromecoloma/zendesk-cli/main/install.sh | bash -s -- --uninstall

Or locally:

./install.sh --uninstall

📖 Usage

Basic Commands

# Initialize configuration interactively
zendesk-cli init

# List all tickets
zendesk-cli list-tickets

# List tickets with specific status
zendesk-cli list-tickets open
zendesk-cli list-tickets pending
zendesk-cli list-tickets solved

# Create a new ticket
zendesk-cli create-ticket "Bug report" "Found an issue with the application"

# Create a ticket with priority
zendesk-cli create-ticket "Critical bug" "System is down" urgent

Advanced Usage

# Use raw JSON output (no formatting)
ZENDESK_FORMAT=raw zendesk-cli list-tickets

# Debug mode (shows loaded config file)
ZENDESK_DEBUG=1 zendesk-cli list-tickets

⚙️ Configuration

Quick Setup with Init Command

The easiest way to set up configuration:

zendesk-cli init

This interactive command will:

• Guide you through getting your API token
• Help you set up your Zendesk subdomain and email
• Create a properly formatted .zendeskrc file

Configuration File Locations

Zendesk CLI looks for configuration files in these locations (first found wins):

1. ./.zendeskrc (project-specific)
2. ~/.zendeskrc (user-specific)
3. ~/.config/zendesk-cli/.zendeskrc (XDG config)

Sample Configuration (~/.zendeskrc)

# API Authentication (required)
ZENDESK_SUBDOMAIN="mycompany"  # for mycompany.zendesk.com
ZENDESK_EMAIL="user@company.com"
ZENDESK_API_TOKEN="your_zendesk_api_token_here"

# Output format (optional)
ZENDESK_FORMAT="pretty"  # or "raw"
ZENDESK_DEBUG="0"        # or "1" for debug info

Getting Your API Token

1. Go to: https://[YOUR_SUBDOMAIN].zendesk.com/admin/apps-integrations/apis/api-tokens
2. Click "Add API token"
3. Copy your API token
4. Add it to your config file

🎯 Tab Completion

Zendesk CLI includes intelligent Zsh completion that provides:

• Command completion: zendesk-cli li<TAB> → list-tickets
• Flag completion: zendesk-cli create-ticket --<TAB> → shows available flags
• Context-aware options: Different commands show relevant flags

🔧 Commands Reference

Command	Description	Arguments
init	Interactive configuration setup	None
list-tickets	List tickets	[status] (open, pending, solved)
create-ticket	Create new ticket	"subject" "description" [priority]

📝 Environment Variables

Variable	Description	Default
ZENDESK_FORMAT	Output format (pretty|raw)	pretty
ZENDESK_DEBUG	Debug mode (0|1)	0

🛠️ Development

Local Development Setup

git clone https://github.com/jeromecoloma/zendesk-cli.git
cd zendesk-cli

File Structure

zendesk-cli/
├── zendesk-cli          # Main script
├── completions/         # Zsh completion
│   └── _zendesk_cli
├── install.sh          # Installation script
├── README.md           # This file
├── LICENSE             # MIT License
└── examples/           # Configuration examples
    └── .zendeskrc.example

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 Examples

Complete Workflow

# 1. Setup configuration interactively
zendesk-cli init

# 2. List all tickets to see current workload
zendesk-cli list-tickets

# 3. List only open tickets
zendesk-cli list-tickets open

# 4. Create a new ticket
zendesk-cli create-ticket "Bug report" "Found an issue with login system" high

Alternative Manual Setup

# 1. Configure API credentials manually
echo 'ZENDESK_SUBDOMAIN="mycompany"' > ~/.zendeskrc
echo 'ZENDESK_EMAIL="user@company.com"' >> ~/.zendeskrc
echo 'ZENDESK_API_TOKEN="your_token_here"' >> ~/.zendeskrc

# 2. Continue with workflow above

Daily Usage

# Check morning tickets
zendesk-cli list-tickets open

# Create tickets for bugs found
zendesk-cli create-ticket "UI Bug" "Button not working on mobile" normal

# Check all pending tickets
zendesk-cli list-tickets pending

# Create urgent tickets
zendesk-cli create-ticket "System Down" "Database connection failed" urgent

🆘 Troubleshooting

Common Issues

Command not found:

# Check if ~/bin is in PATH
echo $PATH

# Add to ~/.zshrc if missing
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied:

# Make script executable
chmod +x ~/bin/zendesk-cli

API authentication failed:

# Check your API credentials
zendesk-cli list-tickets

# Verify config file
cat ~/.zendeskrc

Tab completion not working:

# Rebuild completion cache
rm ~/.zcompdump*
exec zsh

No config file found:

# Use interactive setup (recommended)
zendesk-cli init

# Or create config file manually
echo 'ZENDESK_SUBDOMAIN="mycompany"' > ~/.zendeskrc
echo 'ZENDESK_EMAIL="user@company.com"' >> ~/.zendeskrc
echo 'ZENDESK_API_TOKEN="your_token"' >> ~/.zendeskrc

Configuration errors:

• The tool now shows helpful error messages with clear instructions
• Missing variables are highlighted with suggestions
• Configuration errors won't crash the script

🔒 Security Best Practices

1. Keep API tokens secure - don't commit them to version control
2. Use environment-specific configs for different projects
3. Regularly rotate API tokens if compromised
4. Set proper file permissions on config files (600)

📄 License

MIT License - see LICENSE file for details.

---

Found this useful? ⭐ Star the repo and share with your team!