Install and download

How to get grokbot-tui on Linux, macOS and Windows, and how to start it.

Downloads by OS

Every release has these files; the links below always point at the latest one.

The -ffmpeg archives (grokbot-tui-ffmpeg-<target>…) add video playback with FFmpeg linked in. Each file has a .sha256 next to it, and sha256.sum lists them all.

After installing, run grokbot-tui --mock to try the UI offline, then grokbot-tui and log in. man grokbot-tui (from the .deb/.rpm or make install) lists every flag and environment variable.

Shell completions (1.41.0)

grokbot-tui completes its flags and subcommands (including mcp serve|token|config and completions) in bash, zsh, fish, PowerShell and elvish. The scripts are generated from the CLI definitions. Release archives carry them in a top-level completions/ folder and a test keeps them current (UPDATE_COMPLETIONS=1 cargo test completions rewrites them). In the app: /help completions.

Installed automatically:

The release archives (.tar.xz, .zip) carry all five scripts in completions/. With the shell installers, MSI, .pkg or Homebrew, print the script for your shell yourself:

source <(grokbot-tui completions bash)                                   # bash: add to ~/.bashrc
grokbot-tui completions zsh > ~/.zfunc/_grokbot-tui                       # zsh: fpath=(~/.zfunc $fpath) before compinit
grokbot-tui completions fish > ~/.config/fish/completions/grokbot-tui.fish
grokbot-tui completions elvish > ~/.config/elvish/lib/grokbot-tui.elv     # then `use grokbot-tui` in rc.elv

grokbot-tui completions powershell | Out-String | Invoke-Expression      # add to $PROFILE

Note for zsh with .deb: Debian's zsh reads /usr/share/zsh/vendor-completions; run compinit again (or start a new shell) after installing.

Install

Prebuilt packages are attached to each GitHub Release (see PACKAGING.md for how releases are made and what is published where):

• Shell installer (macOS/Linux): the grokbot-tui-installer.sh command shown in the release notes
• PowerShell (Windows): the grokbot-tui-installer.ps1 command shown in the release notes
• Windows: grokbot-tui-x86_64-pc-windows-msvc.msi · macOS: grokbot-tui-<arch>.pkg (unsigned)
• Debian/Ubuntu: sudo apt install ./grokbot-tui_<ver>-1_<arch>.deb
• Fedora: sudo dnf install ./grokbot-tui-<ver>-1.<arch>.rpm
• Arch Linux (local package): download the grokbot-tui-bin-<ver>-1-<arch>.pkg.tar.zst from the release page (when present), then:
• verify (optional): gpg --verify grokbot-tui-bin-<ver>-1-<arch>.pkg.tar.zst.asc grokbot-tui-bin-<ver>-1-<arch>.pkg.tar.zst
• install: sudo pacman -U ./grokbot-tui-bin-<ver>-1-<arch>.pkg.tar.zst
• update: repeat with a newer file; pacman replaces the installed version
• uninstall: sudo pacman -R grokbot-tui-bin (or grokbot-tui for the source-built package)
• Homebrew, AUR, winget: once published (see PACKAGING.md), brew install WeirdBrains/tap/grokbot-tui, yay -S grokbot-tui-bin, winget install WeirdBrains.grokbot-tui
• From source: make install from a checkout (see Install from a local checkout)

Install from a local checkout

These build the code in front of you and copy the result into place. Nothing is fetched from crates.io as an install, and no prebuilt binary is downloaded. Building still needs a Rust toolchain (cargo/rustc, from rustup or your distro), plus libasound2-dev/alsa-lib-devel on Linux.

make                         # build (release)
make install                 # install to ~/.local (or /usr/local as root)
make install PREFIX=/opt/gbt # any prefix; DESTDIR=... for staged/package installs
make install FFMPEG=1        # -ffmpeg variant (FFmpeg built and linked statically)
make uninstall               # same PREFIX/DESTDIR as the install
make vendor && make install OFFLINE=1   # vendor crates once, then build fully offline

Without make, run the script directly: ./install-local.sh [--prefix DIR] [--destdir DIR] [--ffmpeg] [--vendor] [--offline] [--no-build] [--uninstall]. On Windows: .\install-local.ps1 [-Prefix DIR] [-Ffmpeg] [-Vendor] [-Offline] [-Uninstall] (default %LOCALAPPDATA%\Programs\grokbot-tui, added to your user PATH; -Ffmpeg needs vcpkg FFmpeg).

The install puts the binary in PREFIX/bin, docs and THIRD_PARTY.md in PREFIX/share/doc/grokbot-tui, the licence in PREFIX/share/licenses/grokbot-tui, and the example themes, keymap and notify rules in PREFIX/share/grokbot-tui. Uninstall removes only those; your settings and history stay.

Run

cargo run -- --mock                        # offline: fake bots, delayed echo replies
cargo run                                  # real gateway
make install                               # builds and installs the `grokbot-tui` binary
grokbot-tui --data-dir /tmp/gbtest         # different data directory (holds context.db)
grokbot-tui --account work                 # start in an account (or GROKBOT_TUI_ACCOUNT=work)
grokbot-tui --theme solar                  # use a theme for this run only (not saved)
grokbot-tui --list-themes                  # list the theme files (● = in use) and exit

In mock mode any token logs in except bad. Sending reject simulates a 4xx and unknown simulates a 5xx after the prompt has landed.

Edit this page on GitHub