@fredlackey/cli-zulip

Command-line interface for Zulip chat, channels, bots, admin workflows, and automation. JSON output by default so AI agents and scripts can consume it directly, with a human-friendly mode when you're working interactively.

Install

npm install -g @fredlackey/cli-zulip

Usage

Every command except status accepts credentials directly as flags. No setup step is required.

zulip auth whoami \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key>

zulip channel list \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key>

zulip message send \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key> \
  --channel general \
  --topic "Status Update" \
  --content "Hello from cli-zulip"

zulip dm send \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key> \
  --to [email protected] \
  --content "Quick question"

zulip bot list \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key>

zulip event tail \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key> \
  --channel sandbox \
  --topic smoke-test

If you've already run zulip configure, you can omit the credential flags:

zulip auth validate
zulip channel list
zulip topic list --channel general
zulip message list --channel general --topic announce --limit 20
zulip bot list
zulip status

You can also point at a downloaded Zulip config file instead of passing raw credentials:

zulip auth whoami --zuliprc ~/.zuliprc
zulip message list --zuliprc ~/.zuliprc --channel general --topic announce

Configure (Optional)

The configure command is optional. Every command except status accepts credentials directly as flags. You never need to run configure to use this tool. It exists as a convenience so you don't have to pass the same Zulip credentials on every invocation.

zulip configure \
  --site https://chat.example.com \
  --email [email protected] \
  --api-key <key>

Running zulip configure without flags prompts for each value interactively. Credentials are stored in ~/.config/cli-zulip/config.json.

Credential resolution order is:

1. Explicit flags
2. --zuliprc
3. Saved config file

There are no environment variables to set.

To remove the saved config file:

zulip configure --reset

To confirm whether saved credentials are configured and valid:

zulip status

If a required credential is missing at runtime, the error tells you what to supply:

{
  "error": "Missing required value: site. Pass credential flags, --zuliprc, or run \"zulip configure\"."
}

Command Areas

The CLI currently covers:

• auth and connection validation
• server metadata and realm emoji listing
• channels, topics, subscriptions, and default channels
• channel and direct messages
• reactions, files, and event queues
• bots and bot storage
• users, groups, invites, and realm domains
• drafts, scheduled messages, reminders, and snippets
• profile fields, settings, channel folders, and exports

Full Command Reference

For the complete list of commands and flags, see COMMANDS.md.

OpenAPI

A pinned Zulip OpenAPI spec is included at docs/openapi/openapi.yml.

Testing

The repo includes a live smoke runner that exercises the documented happy-path command surface against a real Zulip server:

npm run smoke

It uses the saved CLI config by default, or you can pass --site, --email, and --api-key directly to the smoke script.

Output

All commands write JSON to stdout by default. When run in an interactive terminal, output switches to a human-friendly format with colors. Use the global --json and --interactive flags to override the auto-detection.

Contributing

If you find a gap or have a feature request, open an issue or submit a pull request on GitHub.

Questions?

If you have questions, comments, or just want to talk shop, feel free to reach out.

Fred Lackey
[email protected]
https://fredlackey.com

License

Apache-2.0