Use OS X Text Substitution Preferences in your *nix pipeline
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


A command line utility for using the OS X Text Substitution System Preferences in a unix pipeline. Like sed but for Mac users who are taking advantage of a mostly hidden system preference.

Basic usage is like this:

$ echo "Copyright (c) 2013 Mark Wunsch" | osxsub
  Copyright © 2013 Mark Wunsch

Text Substitutions are available for a handful of Mac applications, and can be set up by going to System Preferences -> Keyboard and selecting the Text tab.

Read more about OS X Text Substitution:

The goals for this program are:

  • Backup your text substitution preferences, along with the ability to
  • Load new preferences, so that you can
  • Share substitution preferences across machines, and
  • Have access to them in a greater set of applications, by
  • Allowing Text Substitutions to be a part of your command line toolkit.

Some more options can be given to the tool to make managing your Preferences easy:

$ osxsub --print
## Print a plist of your substition preferences

$ osxsub --merge PATH_TO_PLIST
## Merge another plist into your preferences.

$ osxsub --add REPLACE,WITH
## Add a new pair of substitutions (they're turned on by default).

$ osxsub --clear
## Clear all your preferences.

$ osxsub --repl
## Start an interactive session to test out substitutions.

Note: Somewhere between OS X Mavericks and Yosemite the text substitution engine got a little out of whack. If you use osxsub, you might notice that your custom shortcuts do not appear in System Preferences. Because of some weird iCloud sync thing there's also some Core Data database lurking around that complicates all of this. I'm working on trying to make osxsub work well in our new _C L O U D W O R L D_. In the mean time, read more about this strange behavior here:

If your changes don't take place after you restart an application, try running this command:

$ defaults read -g NSUserDictionaryReplacementItems

Still trying to understand how to make this stick.


brew install

Alternatively, osxsub is available as a Rubygem.

$ gem install osxsub

Or clone the repository and put the bin directory somewhere on your $PATH.


  • Manpages
  • Documentation
  • Tests

Copyright © 2013 - 2015 Mark Wunsch.