User Guide

This page is intended for end-users who want to use the textual user interface included with hangups.


Once installed, run this command to start hangups:


For help with command line arguments, run:

hangups -h

Logging in

The first time you start hangups, you need to log into your Google account.


Never give your Google account credentials to any application or device that you don’t trust. Logging into Google grants hangups unrestricted access to your account. hangups works this way because Google does not provide any other method to access the Hangouts API.

You will be prompted to enter your Google email address, password, and verification code (if applicable).

If this login method fails, try the manual login method instead:

hangups --manual-login

After a successful login, hangups will save a refresh token allowing it to login automatically. By default, the token is saved to a file in an OS-specific cache directory. The default token file path can be viewed using hangups -h. To specify a different path for the token file, use the --token-path option:

hangups --token-path /path/to/refresh_token.txt

hangups may be deauthorized from your Google account using the Google recently used devices page. hangups will be listed as “hangups” (or “iOS” in older versions).


After connecting, hangups will display the conversations tab, which lists the names of all the available conversations. Use the up and down arrow keys to select a conversation, and press enter to open it in a new tab.

hangups uses a tabbed interface. The first tab is always the conversations tab. Once multiple tabs are open, use ctrl+u and ctrl+d and move up and down the list of tabs. Use ctrl+w to close a tab.

In a conversation tab, type a message and press enter to send it, or use the up and arrows to scroll the list of previous messages. hangups supports readline commands for editing text. See the readlike library documentation for a full list. Note that some of hangouts’ bindings conflict with these key combinations, see the Configuration section on how to adjust key bindings.

When new messages arrive, hangups will open a conversation tab in the background, and display the number of unread messages in the tab title. On Linux (with an appropriate desktop notification service running) and Mac OS X, hangups will also display a desktop notification. To mark messages as read, press any key (such as enter) while in a conversation tab.

When the network connection is interrupted, hangups will show a “Disconnected” message in each conversation. When the connection is restored a “Connected” message is shown, and hangups will attempt to sync any messages that were missed during the disconnection. If hangups is disconnected for too long, it will eventually exit.

To exit hangups, press ctrl+e.


hangups may be configured through both command line arguments and a configuration file. See the output of hangups -h for details on using both of these methods.

Keybindings are specified using urwid’s format, for example: ctrl e or shift ctrl e. Some key combinations may be unavailable due to terminal limitations or conflicts.

Colours are specified using urwid’s colors, for example: dark red or Xresources color1. Standard Foreground and Background Colors can be found here for 16 bit palette.

Constants for 88-Color and 256-Color palettes for urwid’s hcolors.


hangups can log information that may be useful for troubleshooting a problem. Run hangups -h to view the default log file path.

To specify a custom log file path, run:

hangups --log /path/to/mylog

To log detailed debugging messages, run:

hangups -d