hcclient 1.14.5

A terminal client for connecting to hack.chat

hcclient

A cross-platform terminal client for hack.chat

Table of Contents

• Introduction
• Features
• Prerequisites
• Installation
• Usage
• Colors
• Configuration
• Notifications
• Updatable Messages
• Contributing

Introduction

"hack.chat is a minimal, distraction-free, accountless, logless, disappearing chat service which is easily deployable as your own service." - hack.chat

hcclient is a configurable and feature-rich cross-platform terminal client for connecting to hack.chat.

Note:  This client is written to be compatible with the official live instance running at https://hack.chat. Compatibility with your own self-hosted instance or other alternate instances is not guaranteed.

Features

Some of the features hcclient has to offer:

• Cross-platform:  Tested to work on Windows, Linux, macOS and Android. See Prerequisites for more information.
• Suggestions:  Starting your message with @ or / will bring up a menu with a list of online users or commands. Cycle through them with arrow keys or continue typing to filter the suggestions even more. Suggestion aggressiveness can be set with --suggest-aggr.
• Configuration:  Generate and load YAML/JSON configuration files with no editing required. Change configuration options from within the client with commands, modifying behaviour and colors without having to restart. See Configuration for more information.
• Desktop notifications:  Receive notifications whenever someone mentions you or sends you a whisper. Android notifications are supported when running on Termux. See Notifications for more information.
• Aliases:  Set aliases for messages and phrases you send often, because why wouldn't you?
• Whisper locking:  Lock the client with a command to send only whispers, preventing accidental information leaks.
• Ignore list:  Message blocking using tripcodes and connection hashes.
• Proxy support:  Connect through SOCKS4, SOCKS5 or HTTP proxies. Tested to work with Tor.

Prerequisites

The main requirement for any platform is a terminal emulator that supports ANSI escape sequences.

For x86_64 Linux, statically and dynamically linked binaries are provided with the interpreter and dependencies bundled in.

On other platforms, python >= 3.10 and pip are required.

A Docker / Podman compatible image is provided.

Installation

On all platforms:

# Install the pip package
pip install hcclient

# Run hcclient
hcclient --help

On Arch Linux, install the source AUR package or binary AUR package with makepkg or an AUR helper.
On other x86_64 Linux distributions:

# Download the latest binary
wget -O hcclient https://github.com/AnnikaV9/hcclient/releases/download/v1.14.5/hcclient-1.14.5-linux-x86-64

# Or the statically linked binary if the above one doesn't work
wget -O hcclient https://github.com/AnnikaV9/hcclient/releases/download/v1.14.5/hcclient-1.14.5-linux-x86-64-static

# Make the binary executable
chmod +x hcclient

# Move it to somewhere in PATH
mv hcclient $HOME/.local/bin/

# Run hcclient
hcclient --help

As a container:

# Download the latest image
wget https://github.com/AnnikaV9/hcclient/releases/download/v1.14.5/hcclient-1.14.5-image.tar.xz

# Install the image
docker/podman load -i hcclient-1.14.5-image.tar.xz

# Run hcclient
docker/podman run --rm -it hcclient --help

Usage

$ hcclient --help

usage: hcclient [-h] [-v] [--gen-config] [--defaults] [--colors]
                [-c CHANNEL] [-n NICKNAME] [-p PASSWORD]
                [-w ADDRESS] [-l FILE] [--no-config] [--no-parse]
                [--clear] [--is-mod] [--no-unicode] [--no-notify]
                [--prompt-string STRING]
                [--timestamp-format FORMAT] [--suggest-aggr 0-3]
                [--proxy TYPE:HOST:PORT]

terminal client for connecting to hack.chat

commands:
  -h, --help                        display this help message
  -v, --version                     display version information
  --gen-config                      generate config file
  --defaults                        display default config values
  --colors                          display valid color values

required arguments:
  -c CHANNEL, --channel CHANNEL     set channel to join
  -n NICKNAME, --nickname NICKNAME  set nickname to use

optional arguments:
  -p PASSWORD, --password PASSWORD  specify tripcode password
  -w ADDRESS, --websocket ADDRESS   specify alternate websocket
  -l FILE, --load-config FILE       specify config file to load
  --no-config                       ignore global config file
  --no-parse                        log received packets as JSON
  --clear                           clear console before joining
  --is-mod                          enable moderator commands
  --no-unicode                      disable unicode UI elements
  --no-notify                       disable desktop notifications
  --prompt-string STRING            set custom prompt string
  --timestamp-format FORMAT         set timestamp format
  --suggest-aggr 0-3                set suggestion aggressiveness
  --proxy TYPE:HOST:PORT            specify proxy to use

Colors

The default color scheme can be overidden with a configuration file. See Configuration for more information.
A list of valid colors can be viewed with --colors.

$ hcclient --colors

Valid colors:
 - black
 - grey
 - red
 - green
 - yellow
 - blue
 - magenta
 - cyan
 - light_grey
 - dark_grey
 - light_red
 - light_green
 - light_yellow
 - light_blue
 - light_magenta
 - light_cyan
 - white

Configuration

A configuration file can be generated with the provided arguments using --gen-config and loaded using --load-config. For example:

hcclient --gen-config

The above command will create config.yml with default options in the working directory, which can then be loaded with:

hcclient -c mychannel -n mynick --load-config <path_to_config.yml>

Generated configuration files are in YAML format by default.
Alternatively, a JSON configuration file can be generated by running --gen-config again in the same directory. Both formats can be loaded the same way.

Override defaults when generating the configuration file by specifying options:

hcclient --no-notify --proxy socks5:127.0.0.1:9050 --gen-config

hcclient searches for config.yml or config.json in the following directories by default:

• Windows:  %APPDATA%/hcclient
• Other platforms:  $HOME/.config/hcclient

Things to note:

• The configuration file does not affect channel and nickname, which have to be specified as flags every time.
• Command-line arguments do not override the configuration file's options. If a configuration file is loaded, all flags except for --channel and --nickname are discarded. Run with --no-config if you want to override the default configuration file. Command-line arguments now do override the configuration file's options.

You can also configure hcclient while it's running, without having to restart it. For example:

> /configset no_notify true

The changes will be applied live and lost once you exit the client, but you can save it to the configuration file with /save
Configuration options can be listed with /configdump

Notifications

Desktop notifications are enabled by default. They can be disabled with --no-notify or /configset no_notify true

hcclient doesn't have a built-in audio file for sound alerts, so you'll have to provide your own.
Place a wave file named tone.wav in the default config directory and it will be played when a notification is sent.

Default config directory location:

• Windows:  %APPDATA%/hcclient
• Other platforms:  $HOME/.config/hcclient

On Linux, libnotify and aplay are required for notifications to work.

On Android, notifications are supported when running on Termux.
Install the Termux:API app and termux-api package and notifications will just work.

Note:   Notifications are not supported in container mode.

Updatable Messages

hack.chat has support for updatable messages, which allows editing previously sent messages on the official web client. This is usually used by bots to display streamed/delayed output.
Since hcclient is a terminal client, editing messages that have been previously printed isn't possible.
However, updateMessage events are still handled, just differently.

When an updatable message is received, it will be printed as per normal but with an unique identifier. For example:

23:06|jEuh/s| [⧗ 84263] [user] hi

Here, 84263 is the message identifier.

As the sender continues to update and edit the message, hcclient will track the changes in memory.
Once the sender sends the complete status, the message will be printed again with the same identifier and all changes applied:

23:06|jEuh/s| [⧗ 84263] [user] hi
...
...
...
23:08|jEuh/s| [✓ 84263] [user] hi guys!

It's displayed as a new message, but it's actually the previous message, edited.

If no complete status is received in 3 minutes, the message will expire. All changes applied so far will be printed like normal, but with the ✗ icon instead.

Note:   If no_unicode is enabled, the ⧗, ✓ and ✗ icons will be replaced with Updatable.ID:, Completed.ID: and Expired.ID: respectively.

Contributing

All contributions are welcome! :D

Please read CONTRIBUTING.md before submitting a pull request.

Credits to everyone here

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to https://unlicense.org