Earlier this week, I wrote about WP TUI, a terminal user interface for writing posts and pages on WordPress. I wrote that post, and now this one with it. Today, I’m pleased to say wptui is now available on pypi and GitHub and I’d love your feedback. It comes with a GPL license just like WordPress, so feel free to inspect, modify, or use it as you please. Remember, it’s free as in speech.
You can check it out here:
Installation and setup
You do not need any special plugin to use this, but you do need the REST API enabled and valid TLS (https) for your site. If your host makes HTTPS complicated, I recommend Pressable. To use WP TUI you do need to install pipx.
Mac: brew install pipx
Linux: apt install pipx or dnf install pipx
Windows: scoop install pipx
Then run pipx ensurepath. Once you have pipx you can install wptui. Run pipx install wptui.
Once installed, create an application password in you WP-Admin and run wptui to get started. The TUI will ask for a host URL, username, and password. The password is stored in your system’s secret backend: MacOS Keychain, Windows Credential Locker, or Linux Secret Service. Your password is not lying around in plaintext and you don’t have to worry about losing it to an upgrade in the future. This does mean it may not work in an SSH environment or a non-standard install. If you’re running a linux without a GUI (a server, for example), this may not be available to you. I’m working on supporting password managers like 1Password or keepass but it’s not there yet.
“Free software” means software that respects users’ freedom and community. Roughly, it means that the users have the freedom to run, copy, distribute, study, change and improve the software. Thus, “free software” is a matter of liberty, not price. To understand the concept, you should think of “free” as in “free speech,” not as in “free beer”.
Once you’re logged in, you should see a list of your posts and keyboard shortcuts along the bottom edge. Type ^n (control + n) to create a new post and start writing.
Usage
It should feel pretty familiar out of the box. Type a headline, ^n to create a new paragraph, then you’re writing a blog post. For inline styling like emphasis and strong use markdown syntax (** for strong, * for emphasis). The post will not be pushed to your WordPress site until you first hit ^s to save the post.
Out of the box, it supports most block types that ship with core. Note, I have not tested them all and it does not support your custom blocks. I would avoid editing them on important posts until you test it somewhere safe. This tool isn’t meant to replace WP-Admin or support complex visuals. It’s a text-based interface. If you add an image, you get a textual representation of that image. (Maybe it’d be cool to generate a representation of the picture someday.) In this way it’s very much an accessibility forward tool. Plus, it has Vim mode. Invoke f2 and you’ll feel right at home and even get an indication of what mode a given block is in.
You can add images with ^g and you’ll get an interactive dialog to choose an image already in your media library, or upload your own.
If you upload your own, you can click and drag the file from your systems browser (Finder, Nautalis, Explorer, etc.), enter the appropriate details (alt text, caption, etc.) and the file will upload.
Publishing
Save a post with ^s to push your draft to your site. To publish, you need to enter the post’s settings (^e) and manually set the post status to published. Other than that, the same default behavior you’d expect from WordPress happens out of the box. The slug is generated, the pub date is updated, etc. I often forget to add tags and categories before I publish, so I like the extra deliberate step of switching the post status from draft to publish. Maybe if I get sick of it, or users request it, it can change to a “publish” button that saves and changes the post status.
Known rough edges
A few things I’ve noticed writing this post and dinking around with it.
- You can’t split a paragraph at the cursor. If you’re editing and realize you wrote two paragraphs without interruption, you have to copy-paste the text to split it.
- You can’t enter an attribution on a block quote.
- When you reach the bottom of your terminal window and add a new paragraph, the cursor and block does not scroll into view.
- Certain interactions seem to break tab navigation (like leaving a list from a list-item). Fortunately, mouse interaction still works to break out. Click the next non-list-item.
- Selecting text across blocks does not work. (You can’t delete the last sentence from a paragraph and the first sentence of the next paragraph.)
- The clipboard is local to the TUI.
^cand^vwill copy and paste within the post. When pasting an item from the system clipboard, you mustshift+ctrl+von Linux orcmd+vin MacOS. This is similar to other TUI text editors, so probably won’t fix this. Worth knowing for those who are new to TUIs. - Unordered lists might exhibit strange nesting.
Roadmap
I don’t have much planned for this beyond a Homebrew release. I’d like users to be able to use this as easily as possible. Between pipx and brew I think that’d get pretty close. I also want it to come in at a pretty tidy payload so it can run on a variety of hardware. New features will come with a cost. It’s only 127.4kb now, so I have plenty of room to work with.
In theory, I could use the abilities API to take any action a properly authenticated user can do in the wp-adimn. It’s tempting to make this a full featured WP management TUI. For now, I plan to keep it primarily for writing and editing blog posts. Any immediate improvements I make will be to address these rough edges and respond to feeback from any users who actually try it out.
After that, the focus will be primarily on increased block and editorial supports. Things like custom post types or more complex blocks are on my mind right now. It could also be interesting to think about other ways to represent images beyond text. Maybe an ANSII represntation or 16 bit rendering? I’ll have to do some researching.
This was a fun project to take on. I’ve always been interested in TUIs. Without Compound Engineering, I don’t think I would have gotten close to this far before life interrupted. I might have started it, gotten as far as editing existing posts and a local save, maybe as far as pushing the change to the site before I lost track of it for years.
This is the kind of thing that gives AI meaningful value to me as a one-time developer who still likes making things but was never particularly fast or committed to projects outside of work. If you give this a try, let me know what you think in the comments or open an issue on GitHub.