Home

Welcome to the Mastui Wiki

Mastui is a modern, fast, keyboard-driven terminal user interface (TUI) and web-accessible client for the Mastodon decentralized social network. Built in Python on top of the powerful Textual framework, Mastui delivers a rich, desktop-class fediverse experience directly inside any terminal emulator or modern web browser.

---

📚 Wiki Documentation Index

Explore the comprehensive guides below to learn how to install, configure, customize, and get the most out of Mastui:

Section	Description
🚀 Installation	Installation guides for standalone Linux packages (.deb, .rpm, .AppImage, Arch PKGBUILD), Windows, pipx, pip, and virtual environments.
🛠️ Building and Packaging	How to build Mastui from source using Poetry, run tests, debug locally, and generate distribution packages via PyInstaller.
📖 Getting Started & Usage	Complete walkthrough of logging in, multi-account profile switching, timeline columns, viewing threads, composing posts, content warnings, polls, and direct messages.
🌐 Web Interface Mode (--web)	Running Mastui as a local or remote web application with interactive WebSocket terminal streaming, mobile browser support, and reverse proxy setup.
⌨️ Keyboard Shortcuts & Customization	Complete reference table of all default keybindings and instructions on re-assigning shortcuts via the UI or keymap.json.
⚙️ Configuration File Format	Deep dive into ~/.config/mastui/ directory layout, .env file settings, profile sandboxing, caching architecture, and secure manual edits.
🎨 Custom Themes & Styling	Guide to built-in themes (Tokyo Night, Dracula, Nord, Retro Green, Light), Textual CSS variables, and creating custom theme palettes in custom-themes.json.
🌍 Language Selection & Reordering	Using the composer language dropdown, ISO language codes, and customizing/re-ordering preferred post languages in settings.
🖼️ Image Rendering & Terminal Challenges	Comprehensive analysis of terminal graphics protocols (Kitty Graphics, Sixel, Halfcell/ANSI), terminal emulator support matrix, and troubleshooting rendering issues.

---

✨ Feature Overview

• Multi-Column Timeline Layout: View Home, Local, Federated, Notifications, and Direct Messages side-by-side. Columns automatically collapse responsively in narrow terminals.
• Multi-Profile Support: Manage multiple Mastodon accounts with fully isolated configuration folders, keymaps, credentials, and SQLite caches.
• Rich Post Composer: Autocomplete for @mentions and #hashtags, interactive poll creator, spoiler/content warning (CW) toggle, visibility switcher, and curated language selector.
• Keyboard-Driven Power: Navigate, boost (b), favourite (l), reply (a), edit (e), delete, open URLs (x), search (/), and switch accounts (u) with single keystrokes.
• Inline Media Previews: High-resolution image previews rendered via Kitty Graphics Protocol (TGP), Sixel, or Unicode ANSI halfcells.
• Web Browser Interface (--web): Run Mastui on headless servers or local machines and access it through any browser or mobile device via WebSockets.
• Custom Theming Engine: Personalize your interface with custom JSON color schemes and instant dark/light switching (d).
• Offline Cache & Fast Scrolling: Local SQLite cache stores timelines for instantaneous startup and offline reading.
• Server-side Filter Integration: View and manage your Mastodon server-side keyword and content filters directly inside the TUI.