Usage

Once The Lounge is installed, a program called thelounge is now available.

In this page:

  1. Client help
  2. Native app
  3. Command line help
  4. Using the correct system user
  5. Starting the server
  6. Specifying a different configuration file
  7. Installing additional themes
  8. Installing plugins
  9. Installing local packages
  10. Configuring The Lounge

Client help

To view available keybinds, autocompletion options, and commands, press the help button in the sidebar next to the settings cog.

This page also checks for The Lounge and package updates, and allows you to read the changelog for the currently installed version.

Native app

The Lounge is a progressive web app (PWA), and can be installed from any modern browser for a native-like experience without having a dedicated app.

An “Add The Lounge to home screen” button should show up in settings when The Lounge is running in private mode.

Push notifications are supported on all platforms except for iOS, due to Apple not supporting web push specification and all browsers being reskins of Safari.

Command line help

To get general information about the program and an overview of the available commands, use the --help (or -h) option:

thelounge --help

To get specific help for a given command, run:

thelounge <command> --help

For example, to know how to use thelounge start and the options available, run:

thelounge start --help

If you need to check which version of The Lounge is installed, use:

thelounge --version

Using the correct system user

Note that all commands must be executed as the same user The Lounge will be run as.

If you installed The Lounge via the package manager on a unix like system and plan to run it as a system service, the user is called “thelounge”. So every command needs to be executed as sudo -u thelounge thelounge <command>, where <command> should be substituted with a subcommand like start or add

Starting the server

To start the server, run the following command:

thelounge start

This will start a server and display something along the lines of:

Configuration file created at /etc/thelounge/config.js.
The Lounge v3.0.0 (Node.js 8.9.2 on linux x64)
Configuration file: /etc/thelounge/config.js
Available at http://:::9000/ in private mode
There are currently no users. Create one with thelounge add <name>.

This tells us a few things:

  • Since it is the first time The Lounge runs, a configuration file was created. Its location depends on how The Lounge was installed (see the installation page).
  • The Lounge can now be accessed at http://localhost:9000/.
  • It has started in private mode, which means only users who have an account can log in. There is no guest access.
  • There are no user accounts as of yet, so in fact, no one can log in for now (see the user management page).

The process can be stopped at any time by hitting Ctrl+C. This will effectively close all connections to remote IRC servers that users are connected to.

Specifying a different configuration file

It can be useful to provide a different location for the configuration file. For example, you might want to store it on another partition, or you might want to run multiple instances with different configurations.

To do so, use the environment variable called THELOUNGE_HOME. It will instruct a location where The Lounge will look for the configuration file, the available users, etc.

For example, to start a server with a configuration located at /tmp/config.js, run:

THELOUNGE_HOME=/tmp thelounge start

Installing additional themes

A list of all available themes can be found on the npm registry and installed with thelounge install. For example, to install a theme called thelounge-theme-solarized, run:

thelounge install thelounge-theme-solarized

The Lounge automatically loads the theme after installation and makes it available in the client settings.

Additionally, any theme can be used as the default one for all clients. See the theme section on the configuration page for more information.

For local themes, see Installing local packages

Installing plugins

A list of some plugins can be found on the npm registry and installed with thelounge install. For example, to install a plugin called thelounge-plugin-closepms, run:

thelounge install thelounge-plugin-closepms

The Lounge automatically loads the plugin after installation and activates it.

For local plugins, see Installing local packages

Installing local packages

During development of packages or if uploading a package to the npm registry is undesired, packages can be installed from the local file system.

That’s done by adding a file: prefix to package name:

thelounge install file:~/path/to/package_dir

Configuring The Lounge

As shown above, The Lounge starts by default in private mode on port 9000.

To change the mode or port quickly, the --config (or -c) option can be used.

For example, to start The Lounge on port 9001, run:

thelounge start --config port=9001

Similarly, to start it in public mode, run:

thelounge start --config public=true

This option can be specified multiple times to match the requested configuration:

thelounge start -c port=9001 -c public=true

However, --config is not limited to setting the port or mode. In fact, any option available in the configuration file can be passed using --config. See the configuration page for a full list.

A few rules apply to the --config option:

  • Nested objects require using a dot-notation. For example:
    thelounge start -c debug.raw=true
    
  • Lists of values must be wrapped with []. For example:
    thelounge start -c transports=[websocket,polling]
    
  • If a value has a whitespace, it must be wrapped in quotes. For example:
    thelounge start -c defaults.name="Cool Network"