Zulip Terminal (zulip-term)

An interactive terminal interface for Zulip.

Changes

Please see the CHANGELOG for released & recent changes.

Installation & Running

We recommend installing zulip-term in a new python virtual environment (venv); with the required python 3.4+, the following should work on most systems:

1. python3 -m venv zulip-terminal-venv (creates a venv named zulip-terminal-venv in the current directory)
2. source zulip-terminal-venv/bin/activate (activates the venv; this assumes a bash-like shell)
3. pip3 install zulip-term (downloads and installs the latest zulip-terminal release from PyPI)

Zulip Terminal installs as zulip-term, so you can then 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.

NOTE: Running in subsequent/different sessions

If you open a different terminal window (or log-off/restart your computer), you'll need to run step 2 of the installation again before running zulip-term, since that activates that virtual environment. You can read more about virtual environments in the Python 3 library venv documentation.

NOTE: The zuliprc file

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.

Example zuliprc file

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

Hot Keys

Command	Key Combination
Show/hide help menu	?
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 the current message	r
Reply mentioning the sender of the current message	@
Reply quoting the current message text	>
Reply privately to the sender of the current message	R
New message to a stream	c
New message to a person or group of people	x
Toggle focus box in compose box	tab
Send a message	Alt Enter / Ctrl d
Narrow to the stream of the current message	s
Narrow to the topic of the current message	S
Narrow to all private messages	P
Narrow to all starred messages	f
Next Unread Topic	n
Next Unread private message	p
Search People	w
Search Messages	/
Search Streams	q
Add/remove thumbs-up reaction to the current message	+
Add/remove star status of the current message	*
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.

Setting up a development environment

Various options are available; we are exploring the benefits of each and would appreciate feedback on which you use or feel works best.

Note that the tools used in each case are typically the same, but are called in different ways.

With any option, you first need to clone the zulip/zulip-terminal repository locally (the following will place the repository in the current directory):

$ git clone [email protected]:zulip/zulip-terminal.git

The following commands should be run in the repository directory, which can be achieved with cd zulip-terminal.

Pipenv

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. Install zulip-term, with the development requirements

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

Pip

1. Manually create & activate a virtual environment; any method should work, such as that used in the above simple installation

   1. python3 -m venv zulip-terminal-venv (creates a venv named zulip-terminal-venv in the current directory)
   2. source zulip-terminal-venv/bin/activate (activates the venv; this assumes a bash-like shell)

2. Install zulip-term, with the development requirements

$ pip3 install -e .[dev]

Development tasks

Once you have a development environment set up, you might find the following useful, depending upon your type of environment:

Task	Pip	Pipenv
Run normally	zulip-term	pipenv run zulip-term
Run in debug mode	zulip-term -d	pipenv run zulip-term -d
Run with profiling	zulip-term --profile	pipenv run zulip-term --profile
Run all tests (including linter)	pytest	pipenv run pytest
Build test coverage report	pytest --cov-report html:cov_html --cov=./	pipenv run pytest --cov-report html:cov_html --cov=./
Check type annotations	./tools/run-mypy	pipenv run ./tools/run-mypy

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.