Installation

Installation Guide

Mastui can be installed through pre-compiled standalone binary packages, Python package managers (pipx or pip), or built directly from source.

---

System Requirements

• Operating System: Linux, macOS, BSD, or Windows 10/11 (with Windows Terminal or PowerShell).
• Python (if installing via pip/source): Python 3.9 or higher (Python 3.11/3.12 recommended).
• Terminal Emulator: A modern terminal supporting UTF-8 and 24-bit TrueColor (e.g., Kitty, WezTerm, Ghostty, Alacritty, iTerm2, Foot, GNOME Terminal, Windows Terminal).
• Optional Clipboard Utility (Linux): wl-clipboard (Wayland) or xclip / xsel (X11) for copying URLs to the system clipboard.

---

1. Standalone Pre-built Packages (Recommended for Non-Python Users)

Every release of Mastui includes standalone binaries that do not require Python to be pre-installed on your system. Download them directly from the GitHub Releases page.

Debian / Ubuntu / Linux Mint (.deb)

# Download the latest .deb package from releases
wget https://github.com/kimusan/mastui/releases/latest/download/mastui_<version>_amd64.deb

# Install using dpkg or apt
sudo dpkg -i mastui_<version>_amd64.deb
sudo apt-get install -f  # resolve any optional desktop integration dependencies

Fedora / RHEL / CentOS / openSUSE (.rpm)

# Download the latest .rpm package
wget https://github.com/kimusan/mastui/releases/latest/download/mastui-<version>-1.x86_64.rpm

# Install using rpm or dnf
sudo dnf install ./mastui-<version>-1.x86_64.rpm
# or on older systems:
sudo rpm -ivh mastui-<version>-1.x86_64.rpm

Universal Linux (.AppImage)

The AppImage runs on any modern Linux distribution without installation:

# Download the AppImage
wget https://github.com/kimusan/mastui/releases/latest/download/mastui-<version>-x86_64.AppImage

# Make executable and launch
chmod +x mastui-<version>-x86_64.AppImage
./mastui-<version>-x86_64.AppImage

Tip: You can move the AppImage to ~/.local/bin/mastui to add it to your shell $PATH.

Arch Linux (.pkg.tar.zst)

# Download the Arch package
wget https://github.com/kimusan/mastui/releases/latest/download/mastui-<version>-1-x86_64.pkg.tar.zst

# Install via pacman
sudo pacman -U mastui-<version>-1-x86_64.pkg.tar.zst

Microsoft Windows

1. Download mastui-<version>-windows-x86_64.zip from GitHub Releases.
2. Extract the ZIP archive into a folder of your choice (e.g., C:\Tools\mastui).
3. Open Windows Terminal (or PowerShell) and execute .\mastui.exe.

---

2. Installing via pipx (Recommended for Python Users)

pipx installs Mastui into an isolated virtual environment and exposes the executable globally in your $PATH.

# Install pipx if not already present
# (Ubuntu/Debian: sudo apt install pipx; macOS: brew install pipx; Fedora: sudo dnf install pipx)
pipx ensurepath

# Install Mastui
pipx install mastui

# To upgrade Mastui in the future
pipx upgrade mastui

---

3. Installing via Standard pip and Virtual Environment

You can install Mastui using Python's standard package manager into a dedicated virtual environment:

# Create a dedicated virtual environment
python3 -m venv ~/.venvs/mastui

# Activate the virtual environment
source ~/.venvs/mastui/bin/activate

# Install mastui from PyPI
pip install mastui

# Run Mastui
mastui

To create a convenient shell alias, add the following to your ~/.bashrc or ~/.zshrc:

alias mastui='~/.venvs/mastui/bin/mastui'

---

4. Installing from Source (Poetry)

If you want to contribute to Mastui or run the absolute latest development version from git:

# 1. Clone the repository
git clone https://github.com/kimusan/mastui.git
cd mastui

# 2. Install Poetry if not already available
pip install poetry

# 3. Install project dependencies
poetry install

# 4. Launch Mastui
poetry run mastui

---

Verifying Your Installation

Once installed, verify that Mastui is correctly detected by running:

mastui --help

You should see the command-line options including --debug, --web, --add-account, and --no-ssl-verify.