For years I’ve had a soft spot for text-based user interfaces. There’s just something about running software in a terminal that feels both elegant and hackerish — retro in form, but oddly timeless in function. That’s why I started tinkering with a new project: Mastui, a Mastodon client for the terminal that’s equal parts retro and modern.

I didn’t build it out of frustration so much as necessity. Sometimes you just want a good text-based Mastodon client. The ones out there? They work, but they didn’t really have the features I needed. Multi-timeline view? Nope. Multi-profile support? Not really. And so, like many projects that end up consuming more of your evenings than you expect, Mastui began.

From web CSS to terminal CSS (sort of)

Mastui is built using Textual, a Python framework that brings web-style design into the world of TUIs. If you’re used to working with HTML and CSS, it feels almost familiar… until it doesn’t. Textual borrows ideas from web design but doesn’t always behave the way you’d expect if you’ve been wrangling CSS in browsers for years. That’s part of the fun, though — it forces you to think differently about layout, flow, and interactivity when your canvas is a terminal window instead of a DOM.

APIs, libraries, and the joy of federated quirks

One of the unexpected joys of this project has been exploring the Mastodon API. Thanks to the excellent mastodon-python library, wiring up timelines, posting, and even error handling has been remarkably straightforward. The API itself is clean, consistent, and makes it easy to experiment. Of course, the Fediverse is bigger than Mastodon. Other servers, like Pleroma, play by slightly different rules — which means you occasionally get formatting quirks and unexpected behavior. But hey, it wouldn’t be the Fediverse if every instance behaved identically.

The Mastui logo

Retro at heart, modern in practice

The “retro” in Mastui comes from the obvious: it’s a TUI. You run it in your terminal, navigate with keys, and embrace that classic text-driven workflow. But under the hood, it’s packed with modern niceties. Mastui supports themes and custom styling. It can render images with Sixel if your terminal supports it, or fall back to half-cell ANSI art when it doesn’t. Some users have even said they find Mastui’s reading flow better than graphical clients, since posts aren’t constantly broken up by inline images — unless you choose to turn them on.

In short, Mastui is retro where it counts, and modern where it matters.

From pet project to community project

I’ll be honest: Mastui started as a personal experiment. I wanted to see how far I could take a TUI client, learn more about Textual, and get my hands dirty with Mastodon’s APIs. But it grew quickly. Too quickly to just let it go. Now it has a small but enthusiastic group of users around the world, and I’ve set up the project to make contributing as easy as possible. There’s a clear CONTRIBUTING.md file, issue tracker, feature request process — the works. If you’ve ever thought about hacking on a terminal app, this might be your chance.

Try it yourself

Mastui is available now, and installation is about as painless as it gets:

pipx install mastui

Everything else you need to know is on the project website and over at the GitHub repo.

So if you’ve ever wanted to scroll your Mastodon timelines with a proper retro-modern vibe — or just want to see how far a terminal app can go in 2025 — give Mastui a spin. Hack the planet, one timeline at a time.