Zulip Terminal (zulip-term)

An interactive terminal interface for Zulip.

Recent changes | Configuration | Hot Keys | Troubleshooting | Development

Supported platforms

• Linux
• OSX
• WSL (On Windows)

Installation

We recommend installing in a dedicated python virtual environment (see below) or using an automated option such as pipx

• Stable - Numbered stable releases are available on PyPI as the package zulip-term

  To install, run a command like: pip3 install zulip-term

• Latest - The latest development version can be installed from the main git repository

  To install, run a command like: pip3 install git+https://github.com/zulip/zulip-terminal.git@master

We also provide some sample Dockerfiles to build docker images in docker/.

Installing into an isolated Python virtual environment

With the python 3.5+ required for running, 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. Run one of the install commands above,

If you open a different terminal window (or log-off/restart your computer), you'll need to run step 2 of the above list 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.

Running for the first time

Upon first running zulip-term it looks for a zuliprc file, by default in your home directory, which contains the details to log into a Zulip server.

If it doesn't find this file, 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

   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.

2. Each time you run zulip-term, you can specify the path to an alternative zuliprc file using the -c or --config-file options, eg. $ zulip-term -c /path/to/zuliprc

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

Configuration

The zuliprc file contains information to connect to your chat server in the [api] section, but also optional configuration for zulip-term in the [zterm] section:

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

[zterm]
# Alternative themes are gruvbox, light and blue
theme=default
# Autohide defaults to 'no_autohide', but can be set to 'autohide' to hide the left & right panels except when focused.
autohide=autohide
# Notify defaults to 'disabled', but can be set to 'enabled' to display notifications (see next section).
notify=enabled

Notifications

Linux

The following command installs notify-send on Debian based systems, similar commands can be found for other linux systems as well.

sudo apt-get install libnotify-bin

WSL

Run powershell as admin and run these commands to install dependencies for showing notifications:

set-executionpolicy remotesigned
Install-Module -Name BurntToast

OSX

No additional package is required to enable notifications in OS X. However to have a notification sound, set the following variable (based on your type of shell). The sound value (here Ping) can be any one of the .aiff files found at /System/Library/Sounds or ~/Library/Sounds.

Bash

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.bash_profile
source ~/.bash_profile

ZSH

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.zshenv
source ~/.zshenv

Hot Keys

General

Command	Key Combination
Show/hide help menu	?
Go back	esc
Redraw screen	Ctrl + l
Quit	Ctrl + C

Navigation

Command	Key Combination
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
Narrow to all private messages	P
Narrow to all starred messages	f
Narrow to messages in which you're mentioned	#
Next unread topic	n
Next unread private message	p

Searching

Command	Key Combination
Search users	w
Search messages	/
Search streams	q
Search topics in a stream	q

Message actions

Command	Key Combination
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
Edit a sent message	e
New message to a stream	c
New message to a person or group of people	x
Narrow to the stream of the current message	s
Narrow to the topic of the current message	S
Narrow to a topic/private-chat, or stream/all-private-messages	z
Add/remove thumbs-up reaction to the current message	+
Add/remove star status of the current message	*
Show message information	i

Stream list actions

Command	Key Combination
Toggle topics in a stream	t
Mute/unmute Streams	m
Show stream description	i

Composing a message

Command	Key Combination
Toggle focus box in compose box	tab
Send a message	Alt Enter / Ctrl d
Autocomplete @mentions, #stream_names and :emoji:	Ctrl + f
Cycle through autocomplete suggestions in reverse	Ctrl + r
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 compose box	Ctrl + L

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

Troubleshooting: Common issues

Unable to render non-ASCII characters

NOTE Releases of 0.3.2 onwards should not have this issue, or require this solution.

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.

Alternatively, you might try different modifier keys (eg. shift, ctrl, alt) with a right-click.

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.

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.

Zulip-term crashed!

We hope this doesn't happen, but would love to hear about this in order to fix it, since the application should be increasingly stable! Please let us know the problem, and if you're able to duplicate the issue, on the github issue-tracker or at #zulip-terminal.

This process would be helped if you could send us the 'traceback' showing the cause of the error, which should be output in such cases:

• version 0.3.1 and earlier: the error is shown on the terminal;
• versions 0.3.2+: the error is present/appended to the file zulip-terminal-tracebacks.log.

Something looks wrong! Where's this feature? There's a bug!

Come meet us on the #zulip-terminal stream on chat.zulip.org.

Contributor Guidelines

Zulip Terminal is being built by the awesome Zulip community.

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.

Please read our commit message guidelines and git guide.

A simple tutorial for implementing the typing indicator is available in the wiki. Follow it to understand the how to implement a new feature for 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 git@github.com: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 (see the recommended installation notes; pipenv can be installed in a virtual environment, if you wish)

$ pip3 install --user pipenv

2. Initialize the pipenv virtual environment for zulip-term (using the default python 3; use eg. --python 3.6 to be more specific)

$ pipenv --three

3. Install zulip-term, with the development requirements

$ pipenv install --dev
$ pipenv run pip3 install -e .[dev]

4. Install mypy manually (mypy is incompatible with pypy, so we don't have this enabled by default)

$ pipenv run pip3 install -r requirements.txt

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 linters	./tools/lint-all	pipenv run ./tools/lint-all
Run all tests	pytest	pipenv run pytest
Build test coverage report	pytest --cov-report html:cov_html --cov=./	pipenv run pytest --cov-report html:cov_html --cov=./

NOTE: The linters and pytest are run in CI (travis) when you submit a pull request (PR), and we expect them to pass before code is merged. Running them locally can speed your development time, but if you have troubles understanding why the linters or pytest are failing, please do push your code to a branch/PR and we can discuss the problems in the PR or on chat.zulip.org.

NOTE: The lint script runs a number of separate linters to simplify the development workflow, but each individual linter can be run separately if you find this useful.

GitLint (optional)

If you plan to add git commits and submit pull-requests (PRs), then we highly suggest installing the gitlint commit-message hook by running gitlint install-hook (or pipenv run gitlint install-hook with pipenv setups). While the content still depends upon your writing skills, this ensures a more consistent formatting structure between commits, including by different authors.

If the hook is installed as described above, then after completing the text for a commit, it will be checked by gitlint against the style we have set up, and will offer advice if there are any issues it notices. If gitlint finds any, it will ask if you wish to commit with the message as it is (y for 'yes'), stop the commit process (n for 'no'), or edit the commit message (e for 'edit').

Other gitlint options are available; for example it is possible to apply it to a range of commits with the --commits option, eg. gitlint --commits HEAD~2..HEAD would apply it to the last few commits.

Debugging Tips

Output using print

The stdout for zulip-terminal is redirected to ./debug.log by default.

If you want to check the value of a variable, or perhaps indicate reaching a certain point in the code, you can simply write

print(variable, flush=True)

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

We suggest the flush=True to ensure it prints straight away.

If you have a bash-like terminal, you can run something like tail -f debug.log in another terminal, to see the output from print as it happens.

Interactive debugging using pudb & telnet

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.

There's no effect in Zulip Terminal after making local changes!

This likely means that you have installed both normal and development versions of zulip-terminal.

To ensure you run the development version:

• If using pipenv, call pipenv run zulip-term from the cloned/downloaded zulip-terminal directory;
• If using pip (pip3), ensure you have activated the correct virtual environment (venv); depending on how your shell is configured, the name of the venv may appear in the command prompt. Note that not including the -e in the pip3 command will also cause this problem.