Configuration

luir is configured in Lua. The first run writes an annotated starter set, one file per concern, with every option present and explained in a comment. These pages go through all of them.

They were last checked against luir 0.4.0. The comments in your own starter files always match the version that wrote them.

The files

They are written to:

/config inside luir prints the path it loaded. To use a different one, pass --config /path/to/config.lua or set LUIR_CONFIG to the same. The other files are looked for beside whichever config.lua that is. luir --init writes the starter set without starting the client, and never overwrites a file that is already there.

How it is read

The config is a Lua program. It runs once at start-up and has to return a table, and config.lua builds that table by require-ing the other files for their parts. The directory holding config.lua is on package.path, so require("server") finds server.lua beside it, and so does any file you split out yourself.

This is the shape of the table config.lua returns:

return {
  server   = { ... },  -- server.lua
  ui       = { ... },  -- ui.lua
  theme    = { ... },  -- theme.lua
  status   = { ... },  -- status.lua
  behavior = { ... },  -- written inline in config.lua
  keys     = { ... },  -- keys.lua returns these three
  aliases  = { ... },
  emotes   = { ... },
}

Anything left out keeps its default. You can delete a file you have no use for as long as you also delete its line in config.lua, or collapse the whole thing back into one file:

return {
  server = {
    url      = "https://lurker.example.com",
    username = "you",
    password = "hunter2",
  },
  ui = { style = "classic" },
  theme = { name = "gruvbox" },
}

Being Lua, it can compute. Name a colour once and use it in several places, or read a secret from the environment with os.getenv rather than writing it down.

When something is wrong

luir refuses a config it cannot make sense of, and says why:

• An unknown key is rejected, naming it and listing the keys that are valid there. A typo never silently does nothing.
• A Lua syntax error reports the file and line.
• A require for a file that does not exist names the file.
• A file that forgets its return is told so.
• An action in keys.lua that does not exist, or a key that will not parse, is refused.

A theme name that matches no scheme is the exception: luir falls back to its own palette rather than refusing to start, and reports the name it did not recognise.

Reloading

F5 re-reads the config and applies it at once: layout, colours, the status bar, keys, aliases and behaviour all change without a restart. The server connection is left alone, so a change to server.lua takes effect the next time luir starts. If the edited config fails to load, the running one stays in place and the error goes to the client log.

state.json

The theme picker (alt+t) remembers your choice in state.json, beside the config, rather than rewriting your Lua and its comments. That choice wins over name in theme.lua until /theme reset forgets it. Nothing in state.json is meant to be edited by hand.

auth.json

When you approve luir in a browser, the token it is given is kept in auth.json, beside the config. It holds a secret, so it is a file of its own, and on Linux and macOS only you can read it. Treat it like a password: do not share it, and keep it out of anything that copies your config elsewhere, such as a dotfiles repository.

luir logout revokes the token and removes it from the file. Deleting the file only forgets the token: the server still counts luir as approved until you revoke it in Lurker under Settings, Authorized apps.

banners/

A banners folder beside the config holds start-up banners of your own. banner_style covers them.

Reading the reference

Each option is listed with its type and its default.

An option described as optional has no default: it does nothing until you set it, and is commented out in the starter file.