Zendesk CLI Skill

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

IMPORTANT: Always use uv run

All commands MUST be run with uv run to ensure dependencies are available:

• CLI commands: uv run zendesk <command>
• Python scripts: uv run python src/zendesk_skill/scripts/<script>.py

Never use python3 or python directly – it will fail with ModuleNotFoundError.

Quick Start

# Test authentication
uv run zendesk me

# Search tickets
uv run zendesk search "status:open priority:urgent"

# Get ticket details
uv run zendesk ticket-details 12345

# Query saved response (path shown in command output)
uv run zendesk query <temp>/zendesk-skill/ticket_details_xxx.json -q comments_slim

Key Concepts

Save First, Query Later

All API responses are automatically saved to <temp>/zendesk-skill/ (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 zendesk ticket-details 12345)
2. Response saved to a JSON file (path shown in output)
3. Use uv run zendesk query <file> -q <query_name> 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

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.

Metrics & Analytics

Views (Queue Management)

Users & Organizations

Authentication

Slack Integration

Configuration

Query Tool

Search Query Syntax

The search command uses Zendesk’s query language:

Time Filters

• created>2024-01-01 – Created after date
• updated<2024-01-15 – Updated before date
• solved>=2024-01-20 – Solved on or after date
• created>1week – Created in last week (relative)

Status

• status:open
• status:pending
• status:solved
• status:closed
• status<solved – New, open, or pending

Priority

• priority:urgent
• priority:high
• priority:normal
• priority:low

Assignment

• assignee:me – Assigned to current user
• assignee:none – Unassigned
• assignee_id:12345 – Specific agent
• group:Support – Assigned to group

Tags

• tags:billing
• tags:urgent
• tags:vip tags:enterprise – Multiple tags (AND)

Type

• type:incident
• type:problem
• type:question
• type:task

People

• requester:user@example.com
• requester_id:12345
• organization:acme
• submitter:agent@company.com

Combinations

status:open priority:urgent tags:escalated
status:pending assignee:me updated>1week
type:problem status<solved
requester:*@bigclient.com status:open

Text Search

• subject:password reset – Search in subject
• description:error – Search in description
• password reset – Search anywhere

Named Queries for jq

After fetching data, use zendesk query with these named queries:

For Ticket Details (ticket-details)

For Search Results (search)

Custom jq Examples

# Get specific fields from ticket
uv run zendesk query file.json --jq '.data.ticket | {id, subject, status, tags}'

# Filter comments by author
uv run zendesk query file.json --jq '[.data.comments[] | select(.author_id == 12345)]'

# Get timestamps only
uv run zendesk query file.json --jq '.data.comments | map({created_at, author_id})'

List Available Queries

uv run zendesk query <file_path> --list

Common Workflows

Investigate a Ticket

# 1. Get full ticket details
uv run zendesk ticket-details 12345
# -> Output includes: file_path (e.g., "<temp>/zendesk-skill/12345/ticket_details_xxx.json")

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

# 3. Get conversation (truncated bodies)
uv run zendesk query <file_path> -q comments_slim

# 4. Check for attachments
uv run zendesk query <file_path> -q attachments

Find Related Tickets

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

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

Check Queue Health

# Get available views
uv run zendesk views

# Check ticket count in queue
uv run zendesk view-count 123

# Get tickets to triage
uv run zendesk view-tickets 123

Analyze CSAT

# Find negative ratings
uv run zendesk satisfaction-ratings --score bad

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

# Investigate specific case
uv run zendesk ticket-details <ticket_id>

Update Ticket Status

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

# Add internal note with Markdown formatting
uv run zendesk 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 zendesk 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 zendesk 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 zendesk 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 zendesk 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 zendesk 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)

   uv run zendesk ticket 12345 --output ./my-ticket.json
   

2. --ticket ID – Organizes files under <temp>/zendesk-skill/{ticket_id}/

   uv run zendesk attachment --ticket 12345 <url>
   # -> <temp>/zendesk-skill/12345/attachments/filename.png
   

3. Default – Falls back to <temp>/zendesk-skill/

Ticket-Based Organization

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

<temp>/zendesk-skill/
├── 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

You need three values:

• Email: Your Zendesk agent email
• API Token: Generated in Zendesk Admin Center (not your password!)
• Subdomain: First part of your Zendesk URL (e.g., mycompany from mycompany.zendesk.com)

Getting Your Credentials

Email: Use the email address you log into Zendesk with.

Subdomain: Look at your Zendesk URL:

• If you access https://acme.zendesk.com, your subdomain is acme
• If you access https://support.mycompany.com, ask your admin for the subdomain

API Token (requires admin access or help from admin):

1. Log in to Zendesk
2. Click the Admin Center icon (gear) in the sidebar
3. Navigate to Apps and integrations → APIs → Zendesk API
4. In the Settings tab, ensure Token Access is enabled
5. Click Add API token
6. Give it a description (e.g., “Claude Code CLI”)
7. Click Copy immediately – the token is only shown once!

Don’t have admin access? Ask your Zendesk administrator to:

1. Create an API token for you, OR
2. Grant you admin access to create your own

Token not working? Common issues:

• Using your password instead of the API token
• Token Access is disabled in Zendesk settings
• Your account doesn’t have API access permissions

Option A: Interactive Setup (recommended)

uv run zendesk auth login
# Prompts for email, token (hidden), and subdomain

Option B: Non-Interactive Setup (for automation)

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

Option C: Environment Variables

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

Option D: Config File (manual)

Create ~/.claude/.zendesk-skill/config.json:

{
  "email": "your-email@company.com",
  "token": "your-api-token",
  "subdomain": "yourcompany"
}

Secure the file:

chmod 600 ~/.claude/.zendesk-skill/config.json

Check Auth Status

uv run zendesk auth status

Verify Auth Works

uv run zendesk me

Remove Saved Credentials

uv run zendesk auth logout

Notes for Claude Code Users

Interactive Authentication

The zendesk 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:

  uv run zendesk 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 zendesk auth status command provides detailed guidance:

uv run zendesk 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 zendesk auth status

# If configured, test it works
uv run zendesk me

Slack Integration

Setup

Configure Slack to receive support reports:

# Interactive mode
uv run zendesk auth login-slack

# Non-interactive mode
uv run zendesk 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 zendesk slack-report

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

# Override channel
uv run zendesk 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 zendesk search "created>2024-12-22 created<2025-01-22"

# 2. Get ticket details for each result (for message analysis)
for ticket_id in $(uv run zendesk query <search_file> -q ids_only | jq -r '.[]'); do
  uv run zendesk ticket-details $ticket_id
done

# 3. Run analysis queries on stored data
uv run zendesk query <ticket_details_file> -q conversation_stats
uv run zendesk query <ticket_details_file> -q call_mentions
uv run zendesk query <search_file> -q by_requester

Available Analytics Queries

Search Results (search):

Ticket Details (ticket-details):

*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):

List Metrics (list-metrics):

Customer Identification

Customers are identified by:

1. Organization – If organization_id is set on the user
2. Email domain – Fallback when no organization is set

To get organization info:

# Get user with organization
uv run zendesk user <user_id>

# Get organization details
uv run zendesk org <org_id>

Python Analysis Script

For comprehensive analysis, use the included script:

# Default: 2-week period ending today
uv run python src/zendesk_skill/scripts/analyze_support_metrics.py [search_file]

# Explicit period
uv run python src/zendesk_skill/scripts/analyze_support_metrics.py search.json --start 2026-01-09 --end 2026-01-23

Options:

• --start DATE – Period start date (YYYY-MM-DD). Default: 14 days ago
• --end DATE – Period end date (YYYY-MM-DD). Default: today
• --output DIR – Output directory

This generates:

• Tickets per customer (by email domain)
• Messages per customer
• Messages per ticket
• Call detection results
• FRT and resolution statistics
• Status and priority breakdown
• JSON output at <temp>/zendesk-skill/support_analysis.json

Tips

1. Don’t hallucinate dates: When constructing date-based queries, verify the current date first:

   date +%Y-%m-%d
   

2. Always check file paths: Command output includes the saved file path – use it for follow-up queries
3. Use named queries first: They’re optimized for common patterns
4. Combine queries: Run multiple jq queries on same file for different views
5. Watch for pagination: Search results may have more pages – check next_page in output
6. Test auth first: Use uv run zendesk me to verify credentials work
7. Use –help: All commands have detailed help: uv run zendesk search --help