Zendesk CLI

A command-line dashboard for the CX team. Get a quick read on queue health, agent workload, SLA status, response times, CSAT scores, and ticket trends — without clicking through Zendesk Explore.

Every command is designed to answer the questions the CX team asks daily: How's the queue? Who's overloaded? Are we hitting SLAs? What are customers writing about?

💡 Tip: To get the most value from this CLI, give Claude access to it, and find the answers you're looking for by chatting instead of entering commands.

Access

This CLI is read-only — it only fetches data from Zendesk and never creates, updates, or deletes anything. It authenticates via OAuth 2.0 (PKCE) with read-only scope, so the token can never modify data. Doist is SOC 2 compliant — access to customer data is restricted to people with a legitimate business need. This tool is not designed for general use across the company.

Quick Start

Clone this repository:

git clone [email protected]:Doist/zendesk-cli.git
cd zendesk-cli
npm install
npm run build
npm link

Run the interactive setup:

zd setup

This opens your browser for OAuth authorization. Sign in to Zendesk, approve the request, and you're done — no API tokens to manage.

Then see what's available:

zd help

Commands

zd setup — Interactive OAuth setup

Authorize the CLI via your browser. Credentials are stored locally in ~/.config/zendesk-cli/.

zd setup

zd guide — Command guide

Show available commands with copy-pasteable examples.

zd guide

zd ticket — View a single ticket

Fetch a ticket's subject, metadata, and full conversation by ID or URL. Useful for cross-referencing a specific ticket with a GitHub issue, or passing ticket context directly to an AI agent.

zd ticket 925873                                  # human-readable view
zd ticket https://doist.zendesk.com/agent/tickets/925873
zd ticket 925873 --json                           # JSON (essential fields)
zd ticket 925873 --json --full                    # JSON (all fields)
zd ticket 925873 --public-only                    # exclude internal comments
zd ticket 925873 --comments-only                  # skip metadata, print conversation

zd status — Queue health snapshot

Ticket counts by status (new, open, pending, hold).

zd status                                         # overall counts
zd status --groups                                # breakdown per group

zd sla — SLA breach overview

Unsolved tickets with active SLA policies, categorized as breached, at-risk, or on-track.

zd sla                                            # default: 2h at-risk threshold
zd sla --at-risk 4                                # custom at-risk threshold (hours)

zd workload — Agent capacity

Per-agent open ticket count, remaining capacity, and today's replies.

zd workload                                       # per-group max load defaults
zd workload --max-load 25                         # override max load for all agents
zd workload --today                               # only show agents active today

zd response-times — Response time metrics

Average and median first reply and resolution times per agent.

zd response-times                                 # last 7 days
zd response-times --from 2025-01-01 --to 2025-01-31  # custom range

zd replies — Agent reply stats

Show public replies per agent within a date range.

zd replies                                        # last 7 days
zd replies --from 2025-01-01 --to 2025-01-31      # custom range
zd replies --today                                # today's replies only
zd replies --tags                                  # include top tags per agent
zd replies --tags --top-tags 10                    # show top 10 tags per agent

zd targets — Daily reply targets

Are you on track with your daily ticket target? Also shows weekly progress. Defaults to your own stats — use --team for the full team view.

zd targets                                        # your progress
zd targets --team                                 # full team view

zd csat — CSAT ratings

Show CSAT scores per agent.

zd csat                                           # last 7 days
zd csat --from 2025-01-01 --to 2025-03-31         # quarterly view

zd insights — Ticket trend analysis

Analyze ticket tags, trending keywords, and volume over time. PII is never exposed — subjects and descriptions are sanitized, and only aggregated counts are output.

zd insights                                       # last 7 days, weekly
zd insights --from 2025-01-01 --to 2025-01-31     # custom range
zd insights --period daily --top 10               # daily granularity, top 10
zd insights --period monthly                      # monthly trends
zd insights --deep                                # also analyze ticket descriptions
zd insights --json > report.json                  # export full report

Options:

• --from <date> / --to <date> — date range (default: 7 days, max 31 days advised)
• --top <n> — number of top results (default: 15)
• --period daily|weekly|monthly — time bucketing (default: weekly)
• --deep — include ticket descriptions in keyword analysis (slower)

zd trends — Status-based ticket analysis

Analyze all tickets in a given status — see what's trending by tags, themes, platforms, age, and groups. Complements zd insights (which filters by date range) by filtering by status instead.

zd trends                                         # analyze status:new (default)
zd trends --status open                           # analyze open tickets
zd trends --top 10                                # top 10 results per section
zd trends --json > report.json                    # export full report

Options:

• --status <status> — ticket status to analyze (default: new)
• --top <n> — number of top results per section (default: 15)

Output sections: product breakdown, top tags, subject keywords, thematic grouping, platform breakdown, age distribution, volume by date, group breakdown.

zd dupes — Duplicate/repeat requesters

Users with multiple new/open tickets — find duplicates and repeat contacts.

zd dupes                                          # users with 2+ new/open tickets
zd dupes --min 3                                  # users with 3+ tickets

zd dashboard — ZenPulse Dashboard

Launch ZenPulse in your browser — a live dashboard combining queue health, SLA, trending patterns, CSAT, agent workload, GitHub-linked issues, and more across 14 sections. Opens automatically at localhost:18924.

zd dashboard                                      # start live server at localhost:18924
zd dashboard --snapshot                           # export a static one-page.html and exit

Data refreshes from the Zendesk API on each load. Use the in-page refresh button to pull latest data without restarting.

zd reddit — Reddit Product Feedback Dashboard

Launch a browser dashboard that pulls product feedback from Reddit — sentiment analysis, key themes, and trending discussions. Opens automatically at localhost:18925.

zd reddit                                         # start live server at localhost:18925
zd reddit --snapshot                              # export a static one-page-reddit.html and exit

zd skill — AI agent skills

Install skill files for AI coding agents.

zd skill install claude-code
zd skill install codex
zd skill install cursor
zd skill list
zd skill uninstall codex

Knowledge Base

The CLIs/zendesk-cli/knowledge/ directory contains internal CX knowledge docs that the AI assistant uses to troubleshoot tickets. Each markdown file covers a specific topic (Apple subscription failures, cancellation flows, refund procedures, etc.) and includes step-by-step resolution procedures with admin console commands.

When you run zd skill install claude-code, the installer reads every .md file in the knowledge/ directory and installs each one as a separate skill. This means the AI assistant only loads the relevant topic into context, not the entire knowledge base.

Adding a new knowledge file

1. Create a markdown file under CLIs/zendesk-cli/knowledge/<category>/, e.g. knowledge/billing/refunds.md
2. Start the file with a # Title heading (this becomes the skill description)
3. Commit and push to main

That's it. No code changes needed. Other CX agents pick up the new knowledge by pulling and reinstalling:

git pull
npm run build
zd skill install claude-code --force

Structure guidelines

• One topic per file
• Use clear headings and sections so the AI assistant can quickly locate the relevant part
• Include examples of when to apply specific procedures (e.g., "Use this flow when a user reports a duplicate charge from Apple")
• Document admin console commands with their exact syntax
• Add a "What not to do" section to prevent common mistakes

Output Formats

All data commands support:

• --json — JSON output (essential fields by default)
• --ndjson — one JSON object per line (useful for piping)
• --full — include all fields in JSON output

zd replies --json                                 # essential fields
zd replies --json --full                          # all fields
zd status --json                                  # queue as JSON
zd insights --ndjson | jq .tag                    # pipe to jq

Development

npm test                   # run tests
npm run type-check         # typecheck without emitting
npm run check              # biome lint + format check