Typebar
Download Buy $9

Control a keyboard overlay from Raycast, Alfred or a script

· 6 min read

To control Typebar from Raycast, Alfred or a script, use its typebar:// links or its command-line tool. A line such as open -g "typebar://profile?name=Presenting" switches the overlay to your Presenting profile without taking focus from the app you are in, and anything that can run a shell command can send it. In Raycast, that line goes in a Script Command you can bind to a hotkey. In Alfred, it goes in a workflow with a Hotkey trigger and a Run Script action.

What a script can and cannot do

From a link, the command-line tool, the Shortcuts app or another app, you can:

  • show, hide and place the board
  • switch themes and profiles
  • put a layer on the keys, such as arrows or symbols on the keys you want viewers to watch

What automation never does is type or press keys for you. It changes what the board shows, and nothing in the app you are using.

You do not need a launcher for the basics. Control-Option-Command-K (⌃⌥⌘K) shows or hides the overlay, triple-tap fn does the same, and each profile can have its own “Switch with” shortcut in Settings > Profiles. Scripts earn their place when you want several changes in one go, the same setup before every take, or a hotkey in the launcher you already use all day.

typebar:// links

Here are two links, each sent with the open command that comes with macOS:

open -g "typebar://profile?name=Presenting"
open -g "typebar://layer/show?h=s:arrow.left&j=s:arrow.down&k=s:arrow.up&l=s:arrow.right&fill=blank"

The first switches to the Presenting profile. The second puts a layer on the keys: an arrow on each of H, J, K and L, the keys Vim uses to move, and fill=blank keeps every other key on the board but draws it with no label. Each key=value pair names a key and what goes on it, and s: marks an SF Symbol, Apple’s icon set, so s:arrow.left is a left arrow. open -g "typebar://layer/reset" takes the layer away again, and so does hiding the overlay. It is the quickest way to say “watch these four keys” in a lesson, and Show arrows or symbols on the keys for a game or app tutorial has more on what to put there.

Three details matter when you write your own:

  • Use open -g. The open man page describes the -g flag as “Do not bring the application to the foreground.” With it, the app you are demoing keeps focus, which matters when the cursor is sitting in a text field mid-take.
  • Quote the link. The & between pairs means something to the shell, so an unquoted link is cut off at the first &, and zsh reads the ? as a wildcard.
  • Mind spaces in names. A link cannot hold a plain space; it is written %20. A profile called “Client calls” becomes name=Client%20calls. One-word names keep links simpler, and a link with a profile or theme name Typebar does not have does nothing at all, so check the spelling if nothing changes. The command-line tool below takes the name as you type it: typebar profile "Client calls".

The typebar command-line tool

For scripts, the command-line tool reads more clearly than a long link. Install it from Typebar’s Settings, in the Automation pane; it goes to ~/.local/bin/typebar. A few examples:

typebar themes list
typebar layers list
typebar show --position topRight --hide-after-ms 3000 --symbol q=star.fill

The first two list your themes and your layers, which is handy for getting a theme’s name exactly right before you put it in a command. The third is a brief show: the board appears in the top right with a star on Q, and after 3000 milliseconds, three seconds, it goes back to how it was. If the board was hidden, it hides again; if it was already showing, it stays, and only the star and the new position go. That suits a quick “this is the key” moment in a video.

One thing to set up: ~/.local/bin is not on the Mac’s default PATH, so typing typebar in Terminal may give “command not found”. Either add the folder to your PATH in ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

or call the tool by its full path. In launchers and in the Shortcuts app, always use the full path, $HOME/.local/bin/typebar, because they may not read your shell settings.

Raycast: a Script Command with a hotkey

Raycast can run a shell script as a command of its own, which you can search for, give an alias, or bind to a hotkey.

  1. Open Raycast and run Create Script Command.
  2. Choose Bash, set the mode to Silent, and give it a title, such as “Typebar Presenting”.
  3. Raycast writes the file with its required lines. Below them, add your open -g line.

Leaving out the first line, which names the shell, and any optional lines Raycast adds, the script needs only this:

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Typebar Presenting
# @raycast.mode silent

open -g "typebar://profile?name=Presenting"
  1. In Raycast’s settings, under Extensions, find the new command and record a hotkey for it.

If you switch between several profiles, one command with an argument covers them all. Add this line under the others:

# @raycast.argument1 { "type": "text", "placeholder": "Profile" }

and change the last line to open -g "typebar://profile?name=$1". Type the command’s name in Raycast, fill in the profile name in the argument field, and press Return. Stick to one-word profile names here, because a space would break the link.

Raycast’s quicklinks can hold a typebar:// link too. A Script Command is the better fit when you want -g, or several steps in a row.

Alfred: a workflow

Workflows need Alfred’s Powerpack. In Alfred’s settings, open Workflows and make a new, blank workflow. Add a Hotkey trigger, or a Keyword input if you would rather type a word in Alfred’s box. Connect it to a Run Script action, set its language to zsh, and put your line in the script box:

open -g "typebar://layer/show?h=s:arrow.left&j=s:arrow.down&k=s:arrow.up&l=s:arrow.right&fill=blank"

Make one workflow per job, or one with several hotkeys, each wired to its own Run Script action. The script box takes more than one line, so a single hotkey can switch the profile and then put a layer on the keys.

Plain scripts and other tools

Anything that runs a shell command can do the same. A few that work well:

  • A shell script. Save the lines in a file such as demo.zsh and run it with zsh demo.zsh before a take.
  • AppleScript, through do shell script "open -g 'typebar://profile?name=Presenting'".
  • Keyboard Maestro, with an Execute Shell Script action.
  • The Shortcuts app, which has seven Typebar actions of its own, or a Run Shell Script action (turn on Allow Running Scripts in the Shortcuts app’s settings, under Advanced, first). Show and hide an on-screen keyboard from the Shortcuts app covers those.

A short setup script for a Vim lesson might read:

# demo.zsh: board ready for a Vim lesson
open -g "typebar://profile?name=Presenting"
open -g "typebar://layer/show?h=s:arrow.left&j=s:arrow.down&k=s:arrow.up&l=s:arrow.right&fill=blank"

Run it before every take and each recording starts from the same place. Script a repeatable demo with a command-line keyboard overlay takes the idea further.

If you build a Mac app yourself, Typebar also offers developers one Swift file, and notifications, to show a layer from their own app.

Typebar is $9 once for up to 5 Macs, and free for 24 hours with everything on.

Questions

Can a script make Typebar type text or press shortcuts?

No. Automation changes what the board shows. It never types or presses keys for you.

Why open -g rather than plain open?

The -g flag tells macOS not to bring the app to the foreground, so the app you are working in keeps focus while the overlay changes.

Do I need Raycast or Alfred at all?

No. Terminal, a shell script, Keyboard Maestro or the Shortcuts app can send the same links, and Typebar’s own shortcuts cover showing and hiding.