🧰 zencli — Zendesk in your terminal.

Fast, script-friendly Zendesk CLI for searching tickets, reading ticket threads, performing safe private handoffs, and downloading screenshots/attachments.

Inspired by the UX style of gogcli and wacli:

• clean command tree
• JSON-first automation support
• human-readable terminal output by default
• stable TSV output for shell pipelines
• saved accounts/profiles
• secure secret storage via OS keyring

Status

The project is already usable for read workflows plus a small safe write workflow:

• authenticate with API token or imported OAuth access token
• search tickets by Zendesk query syntax or friendly flags
• inspect ticket metadata
• read comments / conversation history
• inspect audits
• list and download screenshots / attachments
• look up groups and users to build queries
• reassign a ticket to a different team/group
• add an internal note that is always sent as private

Public replies are intentionally not supported by this workflow unless code explicitly opts into them. See docs/spec.md for the broader roadmap.

Features

• Tickets
  • search by status / assignee / group / tags / dates
  • fetch ticket metadata
  • fetch ticket tags only
  • fetch full ticket content
  • fetch comments only
  • fetch audits only
  • reassign a ticket to a different team / group
  • add private internal notes
  • list and download attachments
  • print browser URLs for tickets
• Auth
  • saved profiles/accounts
  • API token auth
  • imported OAuth bearer token auth
  • secrets stored in OS keyring
• Helpers
  • list groups and group members
  • search users and list user groups
• Automation-friendly output
  • --json for machine-readable output
  • --plain for stable TSV output

Install / Build

Choose one of the following options.

Option A: Build locally

git clone <your-repo-url>
cd zencli
make

This builds the binary to:

./bin/zen

Option B: Plain go build

go build -o ./bin/zen ./cmd/zen

Run:

./bin/zen --help

Quick start

1. Create or obtain credentials

API token

You need:

• Zendesk subdomain, such as acme for https://acme.zendesk.com
• account email
• API token

API tokens are created in Zendesk Admin Center and typically require admin access. See docs/auth.md for details.

OAuth token

zencli currently supports importing an existing OAuth bearer token. It does not yet implement the full browser OAuth login / refresh-token flow.

2. Add an account

API token profile

./bin/zen auth add work \
  --subdomain acme \
  --email you@example.com \
  --auth api_token

This prompts for the token securely and stores it in your keychain.

OAuth token profile

./bin/zen auth add work-oauth \
  --subdomain acme \
  --auth oauth_token

Pass token directly

./bin/zen auth add work \
  --subdomain acme \
  --email you@example.com \
  --api-token "$ZENDESK_API_TOKEN"

./bin/zen auth add work-oauth \
  --subdomain acme \
  --oauth-token "$ZENDESK_OAUTH_TOKEN"

3. Test auth

./bin/zen auth test work

4. Search tickets

./bin/zen --account work tickets search --group "Support" --status open
./bin/zen --account work search --assignee me --tag billing --status open
./bin/zen --account work tickets search --raw-query 'type:ticket status<solved group:"Extract"'

5. Read a ticket

./bin/zen --account work tickets content 12345
./bin/zen --account work read 12345

6. Read ticket tags only

./bin/zen --account work tickets tags 12345
./bin/zen --account work --json tickets tags 12345

7. List and download screenshots

./bin/zen --account work tickets attachments list 12345 --include-inline-images
./bin/zen --account work tickets attachments download 12345 --include-inline-images --only-images

8. Move a ticket to another team and add an internal note

In Zendesk, “team” usually maps to a group.

./bin/zen --account work tickets update 12345 \
  --team "Tier 2" \
  --note "Handing off to Tier 2 for deeper investigation."

Use --note-file for longer private notes:

./bin/zen --account work tickets update 12345 \
  --team "Tier 2" \
  --note-file ./handoff-note.txt

Common workflows

Tickets assigned to a team / group

In Zendesk, “team” often maps to a group.

./bin/zen --account work tickets search --group "Extract"

Tickets assigned to a specific assignee

./bin/zen --account work tickets search --assignee "Extract Team"

Reassign a ticket to another team with a private handoff note

./bin/zen --account work tickets update 12345 \
  --team "Extract" \
  --note "Internal handoff: please pick this up for the next investigation step."

Read the full thread including screenshots

./bin/zen --account work tickets content 12345 --include-inline-images
./bin/zen --account work tickets attachments download 12345 --include-inline-images --only-images

Use direct credentials without saving a profile

./bin/zen \
  --subdomain acme \
  --email you@example.com \
  --api-token "$ZENDESK_API_TOKEN" \
  tickets search --status open

Output modes

Default output is human-friendly.

JSON

./bin/zen --account work --json tickets get 12345

Plain TSV

./bin/zen --account work --plain tickets attachments list 12345

Help

Top-level help:

./bin/zen --help

Command help:

./bin/zen tickets --help
./bin/zen tickets search --help
./bin/zen tickets content --help
./bin/zen auth add --help

Make shortcut:

make zen -- --help
make zen -- tickets search --help

Environment variables

Supported global env vars:

• ZEN_ACCOUNT
• ZEN_SUBDOMAIN
• ZEN_EMAIL
• ZEN_API_TOKEN
• ZEN_OAUTH_TOKEN
• ZEN_COLOR
• ZEN_JSON=1
• ZEN_PLAIN=1
• ZEN_KEYRING_PASSWORD

Examples:

export ZEN_ACCOUNT=work
./bin/zen tickets search --status open

export ZEN_SUBDOMAIN=acme
export ZEN_EMAIL=you@example.com
export ZEN_API_TOKEN=...
./bin/zen tickets get 12345

Documentation

• docs/spec.md — product / architecture spec
• docs/usage.md — command guide and examples
• docs/auth.md — auth setup and security notes
• docs/development.md — local development workflow
• docs/releasing.md — tagging and release workflow
• CHANGELOG.md — release notes

Project structure

cmd/zen/                binary entrypoint
internal/cmd/           command definitions
internal/config/        saved account metadata
internal/secrets/       keyring-backed secrets
internal/zendeskapi/    Zendesk HTTP client and response types
internal/outfmt/        output helpers

Development

Build, test, and lint:

make build
make test
make fmt
make lint
make ci

Run the local binary:

make zen -- tickets search --status open

Current limitations

• write support is intentionally narrow: only team/group reassignment and private internal notes
• no public reply flow yet
• no browser-based Zendesk OAuth login flow yet
• saved OAuth auth currently stores an imported bearer token only
• no Homebrew tap / package publishing configured yet
• no shell completion command yet

Security notes

• API tokens and OAuth tokens are sensitive secrets; prefer passing them through the keychain-backed auth add flow
• Zendesk API token permissions are effectively limited by the user role you authenticate as
• for truly lower-privilege testing, use a lower-privilege Zendesk user rather than an admin-backed token
• tickets update only creates private/internal notes; public replies require explicit code-level approval and are not exposed in the CLI flow
• when downloading attachments, zencli only forwards Zendesk auth to the Zendesk host itself

License

MIT. See LICENSE.