Getting Started and Usage

Getting Started & Usage Guide

This guide walks you through logging in, navigating timelines, interacting with posts, composing rich content, managing multiple accounts, and utilizing power features.

---

🔐 First-Time Login and Setup

When launching Mastui for the first time, you are greeted by the Mastui Login modal:

┌────────────────────────────────────────────────────────┐
│                      Mastui Login                      │
├────────────────────────────────────────────────────────┤
│ Welcome to Mastui!                                     │
│ Enter your Mastodon instance to get started.           │
│                                                        │
│ Mastodon Instance: [ mastodon.social                 ] │
│                                                        │
│             [ Get Auth Link ]   [ Cancel ]             │
└────────────────────────────────────────────────────────┘

1. Enter Instance Domain: Type your Mastodon server domain (e.g., mastodon.social, fosstodon.org, infosec.exchange) and press Enter or click Get Auth Link.
2. Authorize Application: Mastui registers a secure client application with your instance and displays an OAuth authorization URL (and copies it to your clipboard if supported).
3. Paste Authorization Code: Open the URL in your web browser, log in to your Mastodon account, click Authorize, copy the provided authorization code, and paste it into the Authorization Code input field in Mastui.
4. Instant Sync: Mastui exchanges the code for an OAuth access token, stores it securely with restricted 0600 file permissions in ~/.config/mastui/profiles/default/.env, and loads your timelines immediately.

---

🖥️ Layout & Navigation

Mastui organizes your feeds into a responsive multi-column layout:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│ Mastui v0.4.0  •  @user@mastodon.social  •  Connected                                  │
├─────────────────────────┬─────────────────────────┬────────────────────────────────────┤
│ Home Timeline           │ Notifications           │ Federated Timeline                 │
├─────────────────────────┼─────────────────────────┼────────────────────────────────────┤
│ > @alice: Hello world!  │ [Boost] @bob boosted... │ @carol: Check out this link!       │
│   💖 12  🔁 4           │ [Fav] @dave liked...    │   💖 3   🔁 1                       │
│                         │ [Mention] @eve: Hey...  │                                    │
│   @frank: Good morning  │                         │ @grace: Photo from my hike...      │
│   💖 5   🔁 0           │                         │   🖼️ [Image: mountain.jpg]         │
└─────────────────────────┴─────────────────────────┴────────────────────────────────────┘
│ [c] Compose  [r] Refresh  [a] Reply  [l] Like  [b] Boost  [x] URLs  [u] Switch  [?] Help   │

Basic Navigation Keys

• Left / Right : Switch active timeline column.
• Up / Down : Navigate up and down through posts in the active column.
• g : Jump directly to the top of the timeline.
• r : Manually trigger an immediate refresh of all enabled timelines.
• d : Instant toggle between Dark and Light color themes.
• ? : Show quick help overlay with all keyboard bindings.
• q : Exit Mastui.

---

⚡ Interacting with Posts

When highlighting any post on a timeline, use these single-key shortcuts:

Key	Action	Description
l	Like / Favourite	Toggle favourite (💖) status on the selected post.
b	Boost / Reblog	Toggle boost (🔁) on the selected post.
a	Reply	Open composer with a thread reference and inline preview of the original post.
e	Edit Post	Edit your own previously published post.
Delete	Delete Post	Delete your own post with confirmation.
p	View Profile / Thread	Open the author's profile view and complete conversation thread.
x	Show URLs	Open the URL Selector modal to copy external links or image URLs.

---

✍️ Rich Post Composer (c)

Press c anywhere to open the composer modal:

┌────────────────────────────────────────────────────────┐
│                      Compose Post                      │
├────────────────────────────────────────────────────────┤
│ Content Warning: [                                   ] │
│                                                        │
│ Post Content:                                          │
│ [ Writing my first post from terminal using Mastui!  ] │
│                                            52/500      │
│                                                        │
│ Visibility: [ Public       ▼ ]  Language: [ English ▼ ]│
│                                                        │
│ [x] Add Poll                                           │
│   Choice 1: [ Option A                               ] │
│   Choice 2: [ Option B                               ] │
│   Expires:  [ 1 Day        ▼ ]  [ ] Allow Multiple     │
│                                                        │
│             [ Post (Ctrl+Enter) ]   [ Cancel (Esc) ]   │
└────────────────────────────────────────────────────────┘

Composer Features

• Mentions & Hashtag Autocomplete: Type @ or # to trigger instantaneous fuzzy autocomplete suggestions sourced from your following list and instance cache.
• Content Warning (CW / Spoiler): Add a spoiler warning so users must click to expand your post body.
• Interactive Poll Builder: Create 2–4 poll choices, configure voting expiration (5 min to 7 days), and allow multiple selection.
• Visibility Levels: Set post visibility to Public, Unlisted, Followers Only, or Direct Mention.
• Language Selector: Easily tag posts with proper language codes (en, da, fr, de, ja, etc.).
• Keyboard Submission: Press Ctrl+Enter or click Post to publish.

---

🔗 URL Extractor Modal (x)

When a post contains links, hashtags, or media attachments, press x:

• Lists all extracted links with numbered shortcuts (1, 2, 3...).
• Pressing the number automatically copies the selected URL to your system clipboard.

---

👥 Multi-Account & Multi-Profile Support (u)

Mastui natively supports managing multiple accounts (e.g., personal, work, bots):

1. Press u to open the Switch Profile modal.
2. Select an existing profile or choose Add New Account.
3. Alternative: Launch from CLI with mastui --add-account.
4. Each profile maintains completely isolated:
   • Credentials (.env)
   • Timelines & SQLite database (cache.db)
   • Custom keybindings (keymap.json)
   • Image cache directory (image_cache/)

---

🔍 Search (/) and Profile Views

Press / to open the global search modal:

• Search for Accounts (@username@domain), Hashtags (#linux), or Status Content.
• Select an account to view their full profile, bio, follower counts, and recent posts.
• Perform Follow / Unfollow, Mute, and Block actions directly from the profile screen.

---

🛡️ Server-Side Filters (i)

Press i to view and configure Mastodon server-side filters:

• View all active filter rules synchronized with your instance.
• Filter by keywords or regex across Public timelines, Home timeline, Notifications, and Conversations.

---

🐞 Log Viewer (F12)

When launching Mastui in debug mode (mastui --debug), press F12 to open an embedded real-time log inspector to view network requests, API responses, and diagnostics.