Zulip Terminal

An interactive terminal interface for Zulip.

Changes

Please see the CHANGELOG for released & recent changes.

Setup:

1. Install the package:

[sudo] pip3 install virtualenv
virtualenv /tmp/zt/
. /tmp/zt/bin/activate
pip3 install zulip-term

2. 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

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

2. Clone the zulip/zulip-terminal repository locally

$ git clone git@github.com:zulip/zulip-terminal.git

3. Install dev requirements

$ cd zulip-terminal
$ pipenv --three
$ pipenv install --dev
$ pipenv run python setup.py develop

4. 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.