tmutil is a handy tool to control Time Machine backups from the command line. I think Apple added it in Lion, but I don’t have a pre-Lion system to verify that.

“man tmutil” and “tmutil” (with no arguments) print helpful usage information, but I was surprised that there were no commands to see what destination Time Machine was currently using. I also couldn’t find a command to tell me if Time Machine was currently running.

I figured tmutil must know that information, so I went looking for it.

The short version:

I found commands to do what I wanted:

tmutil destinationinfo

prints out where Time Machine will backup to.

And these two commands will print out different views of the Time Machine status:

tmutil status
tmutil currentphase

Of course, those commands are NOT documented by Apple, so they may not always work, but they seemed to work for me. YMMV, and they may set your computer on fire. No guarantees, blah blah blah. Taking advice from strangers on the internet is always a possible hazard to your health and happiness.

The long version:

Here’s how I found these undocumented/hidden commands.

First I figured out where the tmutil file lived:

$ which tmutil
/usr/bin/tmutil

Then I figured out what kind of file it was:

$ file /usr/bin/tmutil
/usr/bin/tmutil: Mach-O universal binary with 2 architectures
/usr/bin/tmutil (for architecture x86_64):    Mach-O 64-bit executable x86_64
/usr/bin/tmutil (for architecture i386):    Mach-O executable i386

This told me the tmutil file was an executable program, as opposed to a shell script. If tmutil was a shell script, I would have opened it in a text editor and looked through it for a list of commands. However, since tmutil is an executable program, it won’t yield its secrets to us quite as easily as a shell script.

To dig through executable programs and files you’ll need the “strings” command. It exists on every unix-y OS, including OS X. It describes itself in “man strings” like this:

find the printable strings in a object, or other binary, file

So I ran:

strings /usr/bin/tmutil > tmutil-strings.txt

I opened up tmutil-strings.txt in a text editor (MacVim is my editor of choice, thanks for asking) and looked for a command that I knew existed, “startbackup”, because usually all of the supported command line options for a program will be near each other in the strings output. Here’s what I saw near the “startbackup” text:

/SourceCache/TimeMachineTools/TimeMachineTools-41.3/tmutil/tmutil_common.m
EnumerateModulesWithBlock
processor != NULL
help
enable
disable
startbackup   <<<--- this is what I was searching for
stopbackup
enablelocal
disablelocal
snapshot
delete
restore
compare
setdestination
destinationinfo
addexclusion
removeexclusion
isexcluded
inheritbackup
associatedisk
latestbackup
listbackups
machinedirectory
calculatedrift
uniquesize
verifybackups
currentphase
status
verifyadditions
quickcheckimage
GetVerbForVerbProc
proc != NULL

From this output I guessed that everything between “help” and “quickcheckimage” was a command line option. And it looks like perhaps the “destinationinfo” and “status” commands might be what I was looking for. I ran tmutil with those options and it looked good, case closed!

Here’s a complete list of commands that appeared in the “strings /usr/bin/tmutil” output that aren’t described in “man tmutil” or “tmutil”:

currentphase
destinationinfo
quickcheckimage
status
verifyadditions
verifybackups

I only tried “currentphase”, “destinationinfo”, and “status”. I’ll leave the rest up to curious readers.

So there you go: a brief walkthough of how to discover hidden and undocumented commands in an executable file. Of course, they may be hidden or undocumented for a reason: they may be buggy, unsupported, and have unforeseen and disastrous side effects. Use them at your own risk.