zendesk-cli

Minimal Zendesk CLI for listing tickets and reading ticket comment timelines.

zcli comments returns a slim timeline optimized for terminal review and LLM summarization. By default it includes both public and private comments and emits only:

• author
• time
• visibility (public or private)
• body

Install

npm install -g @tplog/zendesk-cli

Configure

Option 1: interactive setup

zcli configure

Credentials are stored locally in:

~/.zendcli/config.json

The CLI writes this file with restricted permissions.

Option 2: environment variables

This is the recommended option for temporary or CI usage.

export ZENDESK_SUBDOMAIN="your-subdomain"
export ZENDESK_EMAIL="[email protected]"
export ZENDESK_API_TOKEN="your_zendesk_api_token"

Environment variables take precedence over the config file.

Usage

zcli --help
zcli ticket --help
zcli email --help
zcli follower --help
zcli comments --help
zcli search --help
zcli whoami
zcli 12345
zcli ticket 12345 --raw
zcli email [email protected]
zcli email [email protected] --status unresolved
zcli email [email protected] --status open,pending
zcli follower [email protected] --limit 3
zcli comments 12345
zcli comments 12345 --visibility public
zcli comments 12345 --visibility private --sort desc
zcli search "login failure"
zcli search "login failure" --status open --limit 5

Bare arguments are auto-routed: numeric values go to zcli ticket, emails go to zcli email.

Comments output shape

[
  {
    "author": "Support Agent",
    "time": "2026-03-13T06:19:57Z",
    "visibility": "public",
    "body": "Reply text..."
  }
]

Use --visibility public or --visibility private to filter the timeline.

Development workflow

Daily development

1. Create a feature branch from main
2. Develop locally
3. Commit as needed
4. Push branch to GitHub
5. Open a PR to main
6. Merge after CI passes

Example:

git checkout main
git pull
git checkout -b feat/some-change

# work locally
npm ci
npm run build

git add .
git commit -m "feat: add some change"
git push -u origin feat/some-change

Release workflow

This repository uses a safer release flow:

• normal merges to main do not publish automatically
• npm publishing happens only when a version tag is pushed
• the release tag must match package.json version exactly

Publish a new version

1. Make sure main is in the state you want to release
2. Bump the version locally
3. Push main and the new tag
4. GitHub Actions publishes to npm

git checkout main
git pull
npm version patch
git push origin main --tags

Or for a feature release:

npm version minor
git push origin main --tags

This creates tags like v0.1.2, and the publish workflow verifies that the tag matches package.json.

CI/CD

• Publish to npm: runs only on v* tags or manual trigger. Runs tests first, then publishes on success.
• Authentication: uses NPM_TOKEN stored in the repository secrets.

Security notes

• Never commit real Zendesk credentials
• Prefer environment variables for temporary use
• If a token is ever exposed, revoke and rotate it immediately
• Do not store npm publish credentials in the repo or in gitignored files