matterbox / Docs / Installation

Installation

One line on Linux and macOS. This is the long version of it: what that line actually does, every way round it, and the two things it leaves for you to turn on.

matterbox installs per user. Nothing needs root, nothing lands outside your home directory, and there is no daemon running until you ask for one. The binary is a single static-ish executable in ~/.local/bin; the state it keeps — config, token, message cache — lives under ~/.config/matterbox and is not touched by installing or removing it.

The one-line install

$ curl -fsSL https://matterbox.work/install.sh | sh

It prefers to build matterbox on your machine rather than download one, because the optional features are decided at compile time and only a local build can pick them up: inline video needs the FFmpeg development libraries, the --demo soundtrack needs ALSA. The published binaries are pure Go and carry neither. So with Go, git and make present you get the source build; without them the installer falls back to the release binary. It says which one it took, and which features went in.

The source build tracks the latest release tag, not the default branch, so both paths mean the same version of matterbox. Before the first release there is no tag to take and the default branch is what gets built — which is what a clone and a make install would have given you anyway.

Flags, and the variables

Because the script arrives on standard input, flags need sh -s -- in front of them:

$ curl -fsSL https://matterbox.work/install.sh | sh -s -- --prebuilt

The variables exist for piped runs, where sh -s -- is awkward to remember and awkward to read in someone else's setup script:

$ curl -fsSL https://matterbox.work/install.sh | MATTERBOX_PREBUILT=1 sh
$ curl -fsSL https://matterbox.work/install.sh | MATTERBOX_VERSION=v1.0.0 sh

What it checks first

A downloaded binary is verified against the checksums.txt the release publishes, using whichever of sha256sum, shasum or openssl the machine has. If none of them is present, or the checksum file cannot be fetched, the installer stops rather than install something it could not check. A mismatch is a hard error and tells you not to use the download.

The releases cover Linux and macOS on amd64 and arm64. Anything else has to build from source — the installer says so rather than guessing at an asset name. On an Apple Silicon Mac it also asks the kernel whether it is being translated, because a shell running under Rosetta reports x86_64 and would otherwise be handed the slow binary for the rest of its life.

Where things land

Which completion script it writes depends on your $SHELL, so it writes one, not four. If a different matterbox already comes earlier on your PATH, the installer says so and names it — that one, not the new one, is what would run.

From source

$ git clone https://github.com/cornedor/matterbox
$ cd matterbox
$ make install

make install is the fuller of the two routes. It builds with whatever optional features this machine can compile, installs to ~/.local/bin, writes the completion script for your shell, registers the mmauth:// handler on Linux, and drops the listen service in place — disabled. It also appends the fpath lines to ~/.zshrc if they are not there, which the piped installer will not do.

Plain Go works too, and skips the tag detection entirely:

$ go build -o matterbox .

A raw go build or go run outside make is always tag-free, so it works on a machine with no cgo, no pkg-config, no ALSA and no FFmpeg. You get matterbox without inline video or demo audio.

Requirements

Another directory

PREFIX moves the install; the binary goes to $PREFIX/bin. Completion and service paths are XDG ones and stay where the shell and the init system look for them.

$ make install PREFIX=~/apps

A release binary by hand

The tarballs are on the releases page — Linux and macOS, amd64 and arm64, pure Go. Unpack one, check it against the checksums.txt beside it, and drop the binary somewhere on your PATH:

$ sha256sum -c checksums.txt --ignore-missing
$ tar xzf matterbox_linux_amd64.tar.gz
$ install -m 0755 matterbox ~/.local/bin/

Doing it by hand means no completion script, no mmauth:// handler and no service unit. matterbox completion <shell> covers the first — see the CLI page — and matterbox login registers the handler itself on first use.

Optional features

Two features need C libraries, so they sit behind Go build tags. make detects what your machine has and compiles in whatever it can, which is why make install needs no explanation and no flags. You never have to pick.

make tags

What this machine can build, and why it cannot build the rest:

$ make tags

cgo:       yes (CC=gcc)
demoaudio: yes (alsa found)
video:     yes (ffmpeg dev libs found)
tags:      demoaudio,video

Every build prints this block before it starts, so the answer is on screen whether you asked for it or not. A no line names the package that would fix it:

demoaudio: no — ALSA headers not found (Fedora: alsa-lib-devel, …); --demo plays silently
video:     no — ffmpeg dev libs not found (Fedora: ffmpeg-devel, …); video keeps its 🎬 icon

Unlocking the rest

Install the development headers your distribution ships and build again. pkg-config has to be able to find them.

To override the detection rather than satisfy it, name the set yourself. TAGS= with nothing after it turns every optional feature off:

$ make build TAGS=demoaudio
$ make build TAGS=

matterbox --version asks the libraries it actually linked what they are, and prints the build, its optional features and the platform. That is the block worth pasting into a bug report.

Distributing a build

Running a tagged build yourself is unrestricted. Giving one to someone else is where the tags start to matter, because both of them pull in code that matterbox's Apache-2.0 licence cannot cover.

So build tag-free for anything you share. That is exactly what the release binaries are, and the reason they carry no optional features. matterbox --version asks the linked library which FFmpeg you have, and:

$ make third-party-licenses

writes the licence bundle for a build. It checks both the Go dependency graph and the linked FFmpeg, and refuses to produce a bundle for a build it cannot vouch for. The long version of all this is docs/building.md in the repository.

PATH and completion

~/.local/bin is on the PATH by default on most distributions, and on none of them reliably. If it is missing, the installer prints the line for your shell rather than writing it:

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # or ~/.profile
$ fish_add_path ~/.local/bin                              # fish

bash and fish read their completion directories on their own, so the completion script is live in the next shell. zsh needs the directory on its fpath, which is a line in a file of yours — make install appends it, the piped installer prints it:

fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -Uz compinit && compinit

The CLI page has the by-hand form for each shell, PowerShell included, and matterbox completion <shell> --help has the permanent install for it.

The listen service

matterbox listen is the background daemon: it holds a WebSocket open, keeps the message cache warm, and runs your rules. Nothing needs it — the TUI and the CLI work without it — but it is what makes search instant and notifications possible.

make install installs a unit for it and deliberately does not start it, because a daemon that logs in before you have configured anything is just noise. make install-service does that step on its own.

Once you have logged in and configured what you want it to do, turn it on:

$ systemctl --user enable --now matterbox-listen.service   # Linux
$ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.matterbox.listen.plist   # macOS

On older macOS that is launchctl load instead.

First run

Running matterbox with no arguments launches the first-run wizard, which is the screen on the landing page. It writes the config file and signs you in:

$ matterbox welcome

Or write ~/.config/matterbox/config.yaml yourself — the only required key is server_url — and log in separately. matterbox login opens your browser for SSO and saves the token; --user signs in with a username or email instead, and --no-browser just prints the URL for a machine with no browser on it:

server_url: https://mattermost.example.com

matterbox rewrites that file on first run with a comment over every key, so the copy on your disk is a filled-in option reference. The configuration page is the long version, and the CLI page has the rest of login's flags.

Upgrading

Re-run the installer. It prints the version it put in place and, when there was one before, what it replaced:

$ curl -fsSL https://matterbox.work/install.sh | sh

From a clone it is the usual pair. make install re-runs the tag detection, so a build that picks up a library you have installed since needs nothing more than this:

$ git pull
$ make install

To go back to a known-good release, or to hold a machine at one, --version pins both paths:

$ curl -fsSL https://matterbox.work/install.sh | sh -s -- --version v1.0.0

Nothing is migrated on upgrade and nothing needs to be: the config file gains keys with their defaults, and the cache is rebuilt from the server as it goes.

Uninstalling

From a clone, one target undoes the whole install — the binary, the completion scripts for all three shells, the mmauth:// handler, and the service, disabled and unloaded before it is removed:

$ make uninstall

It leaves the fpath line in ~/.zshrc alone, because editing your rc file back is not something a Makefile should do unasked. Without a clone, the same thing by hand:

$ rm ~/.local/bin/matterbox
$ rm -f ~/.local/share/zsh/site-functions/_matterbox \
       ~/.local/share/bash-completion/completions/matterbox \
       ~/.config/fish/completions/matterbox.fish
$ rm -rf ~/.local/share/matterbox                         # the licence bundle
$ rm -f ~/.local/share/applications/matterbox-mmauth.desktop