Termipal

Augment your Mac Terminal with easy native UI

Instant, native micro-GUIs for shell scripts and command line apps

Command line ❤️ GUI

The Unix command line is powerful... But interactivity isn't its strong suit. There are text-mode UIs like curses, but they're not easy to develop, feel archaic to many users and can't interface with the desktop environment.

Termipal is a small and fast GUI utility that lets you create minimal user interfaces using an easy JSON format.

The UIs you create are fully native using the macOS Cocoa API. They have access to desktop APIs like open panels for picking files, opening links in other apps, etc.

For maximum convenience, Termipal automatically attaches to the bottom edge of your terminal window. This way it's right next to where you're typing. This feature works with the standard Mac Terminal as well as replacements like iTerm.

Termipal — let it be your Terminal's new best pal. *cringe*

“This really is great. I used to have to cd to the directory the file was in, type ff + up arrow, and then change the output and input names. This is so much easier. ”
— Justin Carter, video designer; regularly uses command line for converting files

Minimal runtime for native UI

Termipal is actually a small framework for building JavaScript apps, like Electron.

“Wait, that sounds terrible,” you may be thinking — isn't JavaScript slow and a memory hog?
The answer is: No, not when it's separated from the web browser.

JavaScript itself is fast and lightweight. It's the browser that makes Electron apps so big.
Termipal's entire install is a single binary which is only 150 kB in size.

There's no browser engine in Termipal. It doesn't use HTML or CSS — user interfaces are defined simply as JSON objects. It doesn't even embed a JavaScript runtime; instead it uses the one that comes with macOS and is probably already loaded in your Mac's memory because it's a system component.

The APIs in Termipal are similar to Electron where possible. For example, you can listen to the ready event on the app object, and you can open a file picker dialog by calling dialog.showOpenDialog(). (Don't get the wrong impression: Electron is a large and advanced project whereas Termipal is a dinky little version 0.0.x product that has less than 0.1% of the capabilities of Electron. Think of Electron compatibility as a principle that guides Termipal's API design, rather than any guarantee of present compatibility.)

For creating UIs, a new module called microUI is provided. To update the Termipal interface, call microUI.loadUIDefinition() with a JSON object that describes the UI elements. To associate JavaScript functions with interactions, simply pass an action property value that contains the function's name. That's pretty much all there is to know about the UI framework. You can find a few example scripts in the project's Github repo.

Download & Install

Download prebuilt binary for macOS:
termipal-macos-v0.0.2.zip (44 kB)

The zip file contains the pal executable as well as some example scripts.

You can also get the files by cloning the Termipal git repo on Github.

To install, move pal somewhere in your path, for example /usr/local/bin.

To run a script, pass it as the argument, e.g. pal example.js
For help, just: pal

Note: on first run, you will be prompted to allow Termipal to use Accessibility features. This is needed for the window attach feature.

When Termipal is running, you can close it either by double-clicking anywhere in its window, or by clicking the arrow at the far right. This will trigger the exit event on the app object in your script. (To exit without this event, press Ctrl+C in the terminal where pal is running.)

Frequently Asked Questions

Q: Why JavaScript instead of language X?

Because macOS includes a very fast and easy-to-embed JavaScript runtime as standard, and because millions of people already know JavaScript.

Q: Why does Termipal ask for Accessibility permissions?

The feature of automatically attaching the UI window to the bottom edge of the calling Terminal window is implemented using the macOS Accessibility APIs.
The only information being read from Accessibility is window positions for active apps. Termipal is open source, so you can inspect the source code to verify.

Q: How can I run pal's output as a command?

eval "$(pal example.js)"

Q: Can I make the window larger?

Currently the Termipal window's size is restricted to one line, with the width set to match the calling terminal window. This limitation is intentional: I'd like you to think of Termipal as another form of line input for shell scripts. If you need an UI with multiple stages, simply call Termipal multiple times from a shell script. (This way the architecture of your command line tool remains in "Unix land" rather than "JavaScript land".)

Q: Does Termipal work over an SSH connection?

No, it's a native macOS app, so it only works locally... But it would be fun (and perhaps quite useful) to offer Termipal as a client/server system: you'd run a GUI server on the Mac and call into it using a pal client on the remote system where you're ssh'd in. This would be sort of like a baby version of X11. If you want this feature, please let me know in e.g. Github issues, or via contact info below.

Mailing list

Get informed on updates:

Open source

Termipal is open source and licensed under the GPL v3 license.

You can view and download the source at the git repo on Github.

Follow the author

Termipal is made by Pauli Olavi Ojala.

Twitter: @pauliooj

Email: pauli (at) lacquer (dot) fi

Termipal was originally made for automating tasks at Vidpresso, the awesomest choice for live streaming.