A terminal interface for Zulip.
Switch branches/tags
Nothing to show
Clone or download

README.md

Zulip Terminal

An interactive terminal interface for Zulip.

Zulip chat PyPI Python Versions Build Status Coverage status Checked with mypy

Setup:

  1. Install the package:
[sudo] pip3 install virtualenv
virtualenv /tmp/zt/
. /tmp/zt/bin/activate
pip3 install zulip-term
  1. Run Zulip Terminal:
$ zulip-term

NOTE: If you use Google/Github Auth to login into your zulip organization then you don't have a password and you need to create one. Please go to your <Your Organization URL>/accounts/password/reset/ (eg: https://chat.zulip.org/accounts/password/reset/) to create a new password for your associated account.

Alternatively, you can specify the location of zuliprc using the -c option

$ zulip-term -c /path/to/zuliprc

Example zuliprc file

[api]
email=example@example.com
key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
site=https://realm.zulipchat.com

[zterm]
# Theme can also be set to 'blue' and 'light'
theme=default

Hot Keys

Command Key Combination
Go Back esc
Previous message Up / k
Next message Down / j
Go left left / h
Go right right / l
Scroll up PgUp / K
Scroll down PgDn / J
Go to the last message G / end
Reply to a message r
Reply to an author R
Reply mentioning sender of the message @
Reply quoting the message text >
New stream message c
New private message x
Toggle focus box in compose box tab
Send a message Alt Enter
Narrow to a stream S
Narrow to a topic s
Narrow to private messages P
Next Unread Topic n
Next Unread PM p
Search People w
Search Messages /
Search Streams q
Add/remove thumbs-up reaction on a message +
Add/remove star status of a message *
Display help menu ?
Jump to the Beginning of line Ctrl + A
Jump backward one character Ctrl + B /
Jump backward one word Meta + B
Delete one character Ctrl + D
Delete one word Meta + D
Jump to the end of line Ctrl + E
Jump forward one character Ctrl + F /
Jump forward one word Meta + F
Delete previous character Ctrl + H
Transpose characters Ctrl + T
Kill (cut) forwards to the end of the line Ctrl + K
Kill (cut) backwards to the start of the line Ctrl + U
Kill (cut) forwards to the end of the current word Meta + D
Kill (cut) backwards to the start of the current word Ctrl + W
Paste last kill Ctrl + Y
Undo last action Ctrl + _
Jump to previous line Ctrl + P /
Jump to next line Ctrl + N /
Clear screen Ctrl + L

Note: You can use arrows, home, end, Page up and Page down keys to move around in Zulip-Terminal.

Development

For development, the setup process is a little different.

  1. Install pipenv
$ curl https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
$ python3 /tmp/get-pip.py --user
$ printf '\nexport PATH="%s:$PATH"\n' '${HOME}/.local/bin' | tee -a ~/.bashrc
$ python3 -m pip install --user pipenv
  1. Clone the zulip/zulip-terminal repository locally
$ git clone git@github.com:zulip/zulip-terminal.git
  1. Install dev requirements
$ cd zulip-terminal
$ pipenv --three
$ pipenv install --dev
$ pipenv run python setup.py develop
  1. Run the client
$ pipenv run zulip-term

Running tests

  • To run all tests:
pipenv run pytest
  • To generate coverage report for tests:
pipenv run pytest --cov-report html:cov_html --cov=./
  • To run the linter:
pipenv run pytest --pep8
  • To check the type annotations, run:
pipenv run ./tools/run-mypy
  • To open in debug mode:
pipenv run zulip-term -d
  • To profile runtime:
pipenv run zulip-term --profile

Contributor Guidelines

Zulip Terminal is being build by an awesome community of Zulip.

To be a part of it and to contribute to the code, feel free to work on any issue or propose your idea on #zulip-terminal.

Do checkout our commit message guidelines and git guide.

A simple tutorial for implementing typing indicator is available in the wiki. Follow it to understand the how to implement a new feature for zulip-terminal.

Debugging Tips

The stdout for zulip-terminal is set to ./debug.log by default. If you want to check the value of a variable, you can simply write

print(variable)

and the value of the variable will be printed to ./debug.log.

If you want to debug zulip-terminal while it is running, or in a specific state, you can insert

from pudb.remote import set_trace
set_trace()

in the part of the code you want to debug. This will start a telnet connection for you. You can find the IP address and port of the telnet connection in ./debug.log. Then simply run

$ telnet 127.0.0.1 6899

in another terminal, where 127.0.0.1 is the IP address and 6899 is port you find in ./debug.log.

Need Help?

Come meet us at Zulip.

Troubleshooting: Common issues

Unable to render non-ASCII characters

If you see ? in place of emojis or Zulip Terminal gives a UnicodeError / CanvasError, you haven't enabled utf-8 encoding in your terminal. To enable it by default, add this to the end of you ~/.bashrc:

export LANG=en_US.utf-8
Unable to open links

If you are unable to open links in messages, then try double right-click on the link. If you are still facing problems, please discuss it at #zulip-terminal or open an issue for it mentioning your terminal name, version, and OS.

[DEV] No effect on Zulip Terminal on making local changes

This means that you have installed both Normal and development versions of zulip-terminal. For running the development version, call pipenv run zulip-term from the cloned / downloaded zulip-terminal directory.

Above mentioned hotkeys don't work as described

If any of the above mentioned hotkeys don't work for you, feel free to open an issue or discuss it on #zulip-terminal.