Zendesk

Zendesk CLI Skill

A command-line interface for comprehensive Zendesk API integration. Run commands via uv run zd-cli in the skill directory.

> Running commands > > - Installed (recommended): uvx zd-cli > - Development (cloned repo): uv run zd-cli from the repo directory > > Never use bare python3 zd-cli — dependencies won't be available. All examples below use uv run zd-cli; substitute uvx zd-cli if running outside the repo.

Quick Start

# Test authentication
uv run zd-cli me

# Search tickets
uv run zd-cli search "status:open priority:urgent"

# Get ticket details
uv run zd-cli ticket-details 12345

# Query saved response (path shown in command output)
uv run zd-cli query /zd-cli-/ticket_details_xxx.json -q comments_slim

Key Concepts

Save First, Query Later

All API responses are automatically saved to /zd-cli-/ (system temp directory) with:

• Metadata: Command, parameters, timestamp, item count
• Structure: Auto-extracted schema showing field types
• Suggested queries: Command-specific jq queries
• Data: Full API response

Workflow pattern:

1. Run a command (e.g., uv run zd-cli ticket-details 12345)
2. Response saved to a JSON file (path shown in output)
3. Use uv run zd-cli query -q to extract specific data
4. Avoid re-fetching - work with stored files

Why This Matters

Zendesk API responses can be very large (comments with HTML, many custom fields). By saving locally and using jq:

• Context window is preserved (only extract what's needed)
• No redundant API calls
• Complex analysis can use multiple queries on same data

Command Reference

Ticket Commands

| Command | Description | Example | |---------|-------------|---------| | search | Search tickets with query | uv run zd-cli search "status:open" | | ticket | Get ticket by ID | uv run zd-cli ticket 12345 | | ticket-details | Get ticket + all comments | uv run zd-cli ticket-details 12345 | | linked-incidents | Get incidents linked to problem | uv run zd-cli linked-incidents 12345 | | attachment | Download attachment file | uv run zd-cli attachment --ticket 12345 |

Write Operations

All write commands (create-ticket, add-note, add-comment) support Markdown formatting by default. Content is converted to HTML for reliable rendering in Zendesk Agent Workspace. Use --plain-text to send as plain text instead.

| Command | Description | Example | |---------|-------------|---------| | update-ticket | Update ticket properties | uv run zd-cli update-ticket 12345 --status pending | | create-ticket | Create new ticket (Markdown) | uv run zd-cli create-ticket "Subject" "**Bold** description" | | add-note | Add internal note (Markdown) | uv run zd-cli add-note 12345 "**Investigation:** found the issue" | | add-comment | Add public comment (Markdown) | uv run zd-cli add-comment 12345 "Here are the steps:\n- Step 1\n- Step 2" |

Metrics & Analytics

| Command | Description | Example | |---------|-------------|---------| | ticket-metrics | Get reply/resolution times | uv run zd-cli ticket-metrics 12345 | | list-metrics | List metrics for tickets | uv run zd-cli list-metrics | | satisfaction-ratings | List CSAT ratings | uv run zd-cli satisfaction-ratings --score bad | | satisfaction-rating | Get single rating | uv run zd-cli satisfaction-rating 67890 |

Views (Queue Management)

| Command | Description | Example | |---------|-------------|---------| | views | List available views | uv run zd-cli views | | view-count | Get ticket count | uv run zd-cli view-count 123 | | view-tickets | Get tickets from view | uv run zd-cli view-tickets 123 |

Users & Organizations

| Command | Description | Example | |---------|-------------|---------| | user | Get user by ID | uv run zd-cli user 12345 | | search-users | Search users | uv run zd-cli search-users "john@example.com" | | org | Get organization by ID | uv run zd-cli org 67890 | | search-orgs | Search organizations | uv run zd-cli search-orgs "Acme" |

Authentication

| Command | Description | Example | |---------|-------------|---------| | auth login | Configure Zendesk API token credentials | uv run zd-cli auth login | | auth login-oauth | OAuth 2.0 login (opens browser) | uv run zd-cli auth login-oauth --subdomain co | | auth status | Check auth configuration (token + OAuth) | uv run zd-cli auth status | | auth logout | Remove API token credentials | uv run zd-cli auth logout | | auth logout-oauth | Remove OAuth token | uv run zd-cli auth logout-oauth | | auth login-slack | Configure Slack webhook | uv run zd-cli auth login-slack | | auth status-slack | Check Slack configuration | uv run zd-cli auth status-slack | | auth logout-slack | Remove Slack configuration | uv run zd-cli auth logout-slack |

Slack Integration

| Command | Description | Example | |---------|-------------|---------| | slack-report | Send support report to Slack | uv run zd-cli slack-report [analysis_file] | | markdown-report | Generate detailed markdown report | uv run zd-cli markdown-report [analysis_file] -o report.md |

Configuration

| Command | Description | Example | |---------|-------------|---------| | groups | List support groups | uv run zd-cli groups | | tags | List popular tags | uv run zd-cli tags | | sla-policies | List SLA policies | uv run zd-cli sla-policies | | me | Get current user (test auth) | uv run zd-cli me |

Query Tool

| Command | Description | Example | |---------|-------------|---------| | query | Query saved JSON with jq | uv run zd-cli query -q comments_slim |

Search Query Syntax

The search command uses Zendesk's query language:

Time Filters

• created>2024-01-01 - Created after date
• updated=2024-01-20 - Solved on or after date
• created>1week - Created in last week (relative)

Status

• status:open
• status:pending
• status:solved
• status:closed
• `status1week

type:problem status --list

## Common Workflows

### Investigate a Ticket

```bash
# 1. Get full ticket details
uv run zd-cli ticket-details 12345
# -> Output includes: file_path (e.g., "/zd-cli-/12345/ticket_details_xxx.json")

# 2. Get ticket summary (use the file_path from step 1)
uv run zd-cli query  -q ticket_summary

# 3. Get conversation (truncated bodies)
uv run zd-cli query  -q comments_slim

# 4. Check for attachments
uv run zd-cli query  -q attachments

Find Related Tickets

# Find all open tickets from same requester
uv run zd-cli search "requester:user@example.com status:open"

# If it's a problem ticket, find linked incidents
uv run zd-cli linked-incidents 12345

Check Queue Health

# Get available views
uv run zd-cli views

# Check ticket count in queue
uv run zd-cli view-count 123

# Get tickets to triage
uv run zd-cli view-tickets 123

Analyze CSAT

# Find negative ratings
uv run zd-cli satisfaction-ratings --score bad

# Query for details (use file_path from command output)
uv run zd-cli query  --jq '.data.satisfaction_ratings | map({ticket_id, score, comment})'

# Investigate specific case
uv run zd-cli ticket-details 

Update Ticket Status

# Change status and add tag
uv run zd-cli update-ticket 12345 --status pending --tags "waiting-customer,tier2"

# Add internal note with Markdown formatting
uv run zd-cli add-note 12345 "**Escalated** to tier 2, waiting for response.\n\n- Root cause: config mismatch\n- Next steps: awaiting customer confirmation"

# Add plain text note (no Markdown conversion)
uv run zd-cli add-note 12345 "Simple plain text note" --plain-text

Command Options

Global Options

All commands support:

• --output PATH - Custom output file path
• --help - Show command help

Search Options

uv run zd-cli search "query" [OPTIONS]
  --page, -p INT       Page number (default: 1)
  --per-page, -n INT   Results per page (default: 25, max: 100)
  --sort, -s TEXT      Sort field
  --order, -o TEXT     Sort order (asc/desc)

Update Ticket Options

uv run zd-cli update-ticket TICKET_ID [OPTIONS]
  --status, -s TEXT     New status (open, pending, solved, closed)
  --priority, -p TEXT   New priority (low, normal, high, urgent)
  --assignee, -a TEXT   Assignee ID
  --subject TEXT        New subject
  --tags, -t TEXT       Tags (comma-separated)
  --type TEXT           Ticket type

Satisfaction Ratings Options

uv run zd-cli satisfaction-ratings [OPTIONS]
  --score, -s TEXT      Filter: good, bad, offered, unoffered
  --start TEXT          Start time (Unix timestamp)
  --end TEXT            End time (Unix timestamp)

Attachment Options

uv run zd-cli attachment [OPTIONS] URL
  --ticket, -t TEXT     Ticket ID (organizes download under ticket folder)
  --output, -o PATH     Custom output path (overrides --ticket)

File Organization

Output Path Hierarchy

Output paths are determined in this order:

1. --output PATH - Full custom path (highest priority)

``bash uv run zd-cli ticket 12345 --output ./my-ticket.json ``

1. --ticket ID - Organizes files under /zd-cli-/{ticket_id}/

``bash uv run zd-cli attachment --ticket 12345 # -> /zd-cli-/12345/attachments/filename.png ``

1. Default - Falls back to /zd-cli-/

Ticket-Based Organization

When you use ticket-related commands (ticket, ticket-details, ticket-metrics, etc.), files are automatically organized by ticket ID:

/zd-cli-/
├── 12345/                          # Ticket 12345
│   ├── ticket_abc123_1234567890.json
│   ├── ticket_details_def456_1234567891.json
│   └── attachments/
│       └── screenshot.png
├── 67890/                          # Ticket 67890
│   └── ticket_details_ghi789_1234567892.json
└── search_xyz_1234567893.json      # Non-ticket commands at root

Duplicate Filename Handling

When downloading attachments, if a file already exists with the same name, a numeric suffix is added:

• screenshot.png
• screenshot_1.png
• screenshot_2.png

Configuration

Authentication Setup

Two authentication methods are supported. Both can coexist — OAuth takes priority when a valid token is present.

Subdomain: First part of your Zendesk URL (e.g., mycompany from mycompany.zendesk.com)

Option A: OAuth 2.0 (recommended)

Requires an OAuth client configured in Zendesk Admin Center with redirect URL http://127.0.0.1:8080/callback.

uv run zd-cli auth login-oauth --subdomain yourcompany --client-id YOUR_ID --client-secret YOUR_SECRET

Opens a browser for authorization. For headless environments, add --manual to paste the code instead.

Option B: API Token (interactive)

uv run zd-cli auth login
# Prompts for email, token (hidden), and subdomain

Option C: API Token (non-interactive)

uv run zd-cli auth login --email "your@email.com" --token "your-token" --subdomain "yourcompany"

Option D: Environment Variables

export ZENDESK_EMAIL="your-email@company.com"
export ZENDESK_TOKEN="your-api-token"
export ZENDESK_SUBDOMAIN="yourcompany"

Getting an API Token

1. Go to Admin Center > Apps and integrations > APIs > Zendesk API
2. Ensure Token Access is enabled
3. Click Add API token, copy it (shown only once)

Check Auth Status

uv run zd-cli auth status

Verify Auth Works

uv run zd-cli me

Remove Credentials

uv run zd-cli auth logout       # Remove API token
uv run zd-cli auth logout-oauth  # Remove OAuth token

Notes for Claude Code Users

Interactive Authentication

The zd-cli auth login command supports both interactive and non-interactive modes:

• Interactive mode: Prompts for credentials securely (password hidden). This requires running in the user's terminal.
• Non-interactive mode: Pass credentials via flags for automation:

``bash uv run zd-cli auth login --email "you@example.com" --token "your-token" --subdomain "company" ``

When Auth Is Not Configured

If credentials are not configured, commands will fail with a helpful error message. The zd-cli auth status command provides detailed guidance:

uv run zd-cli auth status

If not configured, it will show:

• Which environment variables are set (if any)
• Whether a config file exists
• Setup instructions for all authentication methods

Proactive Auth Check

Before running Zendesk commands for a user, it's helpful to verify auth status first:

# Quick auth check
uv run zd-cli auth status

# If configured, test it works
uv run zd-cli me

Slack Integration

Setup

Configure Slack to receive support reports:

# Interactive mode
uv run zd-cli auth login-slack

# Non-interactive mode
uv run zd-cli auth login-slack --webhook "https://hooks.slack.com/services/..." --channel "#support-reports"

Getting a Webhook URL:

1. Go to your Slack workspace settings
2. Navigate to Apps → Incoming Webhooks (or create a new app)
3. Create a new webhook and copy the URL
4. The URL format: https://hooks.slack.com/services/T.../B.../...

Sending Reports

# Send most recent analysis to configured channel
uv run zd-cli slack-report

# Send specific analysis file
uv run zd-cli slack-report /path/to/support_analysis.json

# Override channel
uv run zd-cli slack-report --channel "#different-channel"

Report Content

The Slack report includes:

• Overview: Total tickets, messages, calls detected, unique customers
• Response Metrics: Average/median FRT, resolution time (when available)
• Status Breakdown: Open, pending, solved, closed counts with icons
• Priority Breakdown: Urgent, high, normal, low counts with icons
• Customer Stats: Tickets and messages per customer (by email domain)
• Top Tickets: Most active tickets by message count with call indicators

Note: Calls are detected on a best-effort basis by searching comment text for keywords like "call", "called", "phone", etc.

Environment Variables

Alternatively, configure via environment variables:

export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
export SLACK_CHANNEL="#support-reports"

Support Analytics Workflow

Support Metrics Report

Generate a comprehensive support report with tickets per customer, messages per ticket, and call detection. Default period is 2 weeks unless otherwise specified:

# 1. Search for tickets in time range
uv run zd-cli search "created>2024-12-22 created -q ids_only | jq -r '.[]'); do
  uv run zd-cli ticket-details $ticket_id
done

# 3. Run analysis queries on stored data
uv run zd-cli query  -q conversation_stats
uv run zd-cli query  -q call_mentions
uv run zd-cli query  -q by_requester

Available Analytics Queries

Search Results (search): | Query | Description | |-------|-------------| | by_requester | Group tickets by requester with counts | | by_organization | Group tickets by organization | | top_requesters | Top 10 requesters by ticket count | | top_organizations | Top 10 organizations by ticket count |

Ticket Details (ticket-details): | Query | Description | |-------|-------------| | messages_by_author | Count messages per author | | conversation_stats | Total messages, public/private, unique authors | | call_mentions | Find comments mentioning calls/phone* | | channel_analysis | Analyze communication channels |

*Note: Calls are detected on a best-effort basis by searching comment text for keywords like "call", "called", "phone", "spoke", etc.

Ticket Metrics (ticket-metrics): | Query | Description | |-------|-------------| | kpi_summary | FRT, resolution times, wait times, reopens | | times | All time-based metrics (calendar & business) | | `efficiency

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andmarios
• Source: andmarios/zendesk-skill
• License: MIT

Install and usage instructions live in the source repository linked above.