Mastui - A TUI Client for Mastodon

Mastui is a terminal user interface (TUI) client for Mastodon, built in Rust using the ratatui library. It provides a fast, keyboard-driven way to interact with Mastodon instances directly from your terminal.

Features

• 🏠 Timeline Viewing: Browse Home, Local, and Federated timelines
• ✏️ Post Creation: Compose new posts and replies
• 💬 Interactive Navigation: Keyboard shortcuts for efficient navigation
• ⭐ Status Interactions: Like, boost, and reply to posts
• 🔐 OAuth Authentication: Secure authentication with Mastodon instances
• 📱 Multiple Views: Timeline, compose, status detail, and notifications

Installation

Prerequisites

• Rust 1.70+ (for compiling from source)

Building from Source

git clone https://git.andmc.ca/rozodru/mastui.git
cd mastui
cargo build --release

The binary will be available at target/release/mastui.

Usage

Authentication

Before using Mastui, you need to authenticate with a Mastodon instance:

mastui auth mastodon.social

Replace mastodon.social with your preferred Mastodon instance. This will:

1. Register Mastui as an application on your instance
2. Open a browser window for authorization
3. Prompt you to enter the authorization code
4. Save your credentials for future use

Starting the TUI

Once authenticated, start the TUI interface:

mastui

Or explicitly run the timeline view:

mastui timeline

Command Line Posting

You can also post directly from the command line:

mastui post "Hello from the terminal! #mastui"

Keyboard Shortcuts

Timeline View

• j / ↓ - Move down to next status
• k / ↑ - Move up to previous status
• Enter - View status details
• r - Reply to selected status
• n - Compose new post
• t - Switch between timelines (Home → Local → Federated)
• m - View notifications
• v - View media attachments
• Ctrl+f - Favorite/unfavorite status
• Ctrl+b - Boost/unboost status
• F5 - Refresh timeline
• q - Quit application

Compose View

• Type to compose your post
• Ctrl+Enter - Send post
• Escape - Cancel and return to timeline

Status Detail View

• r - Reply to status
• Escape / q - Return to timeline

Media View

• j / ↓ - Next media item
• k / ↑ - Previous media item
• Enter / o - Open media externally
• Escape / q - Close media view

General

• Ctrl+C - Force quit from any view

Configuration

Mastui stores its configuration in ~/.config/mastui/config.json. This file contains:

• Instance URL
• Client credentials
• Access token
• User information

The configuration file is created automatically during the authentication process.

Supported Mastodon Features

• ✅ Timeline viewing (Home, Local, Federated)
• ✅ Post creation and replies
• ✅ Status interactions (favorite, boost)
• ✅ Notification viewing
• ✅ Media attachment viewing and external opening
• ✅ Improved HTML content parsing with styled links
• ✅ Account information display
• ✅ Inline image display (works in compatible terminals)
• ✅ Search functionality
• ✅ Auto feed update (configurable interval, default 10 seconds)

Architecture

Mastui is built with:

• Rust - Systems programming language
• ratatui - Terminal user interface library
• tokio - Async runtime
• reqwest - HTTP client for API requests
• serde - Serialization/deserialization
• crossterm - Cross-platform terminal manipulation

The application follows a modular architecture:

• api/ - Mastodon API client and data types
• config/ - Configuration management
• ui/ - TUI components and rendering

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Run cargo build to compile
3. Run cargo test to run tests
4. Use cargo run -- auth <instance> to test authentication
5. Use cargo run to test the TUI

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Mastodon team for creating an amazing decentralized social platform
• The ratatui community for the excellent TUI framework
• The Rust community for the robust ecosystem