An interactive terminal interface for Zulip.

Please see the CHANGELOG for released & recent changes.

We recommend installing zulip-term in a python virtual environment, something like the following:

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

Zulip Terminal installs as zulip-term, so just run:

$ zulip-term

If you see further text, like the following, zulip-term should be loading!

Loading with:
   theme 'default' specified with no config.
   autohide setting 'autohide' specified with no config.
Welcome to Zulip.

Upon first running, zulip-term looks for a zuliprc file, by default in your home directory.

If it doesn't find one, you have two options:

1. zulip-term will prompt you for your server, email and password, and create a zuliprc file for you in that location

2. You can specify the path to an existing zuliprc file using the -c or --config-file options, eg.

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

You can obtain a personal zuliprc file from Zulip servers in your account settings, which gives you all the permissions you have in the web app. Bot zuliprc files can be downloaded from the area for each bot, and will have more limited permissions.

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.

The [api] section of a zuliprc file is relatively standard; zulip-term also reads extra options from the [zterm] section, if they are added:

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

[zterm]
# Theme can also be set to 'gruvbox' ('blue' & 'light' are older themes needing work)
theme=default
# Autohide can also be set to 'no_autohide', to always show the left and right panels
autohide=autohide

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

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 [email protected]: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

• 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

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.

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.

Come meet us at Zulip.

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

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.

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.

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