170 lines
4.3 KiB
Markdown
170 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
mastui
|
|
```
|
|
|
|
Or explicitly run the timeline view:
|
|
|
|
```bash
|
|
mastui timeline
|
|
```
|
|
|
|
### Command Line Posting
|
|
|
|
You can also post directly from the command line:
|
|
|
|
```bash
|
|
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](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
|