Let Me Try to Convince You to Take Screenshots from the Command Line in macOS

I think I need to find a support group for people who are addicted to screen capture utilities. I went through all of the articles on podfeet, and I’ve talked about macOS’s built-in screen capture, Loom, Capto, Monosnap, Teampaper Snap, Parallels Toolbox, Folge, and the now deprecated Clarify and Stepshot Guides. And yet, I’m hear to tell you about yet another way to take screenshots on macOS.

This new method is definitely nerdy and yet not super hard nerdy. Whether it’s actually useful and a method even I’ll stick with is still an open question. I have yet to determine whether this is going to be more or less efficient than using any of the other 28 ways I have of taking screenshots on my Macs. I’m super excited about it though.

As I mentioned, I already taught you everything I know about the unsung hero of the built-in screen capture utility within macOS. It turns out you can control screen capture on a Mac using the command line in the Terminal instead of the graphical user interface (aka GUI). This command has been around since Mac OSX 10.2!

I want to give two shoutouts before we start. J.F. Brissette tipped me off to the existence of the command-line version, and Helma van der Linden reminded me about it and she had a play date with me to really dig into some of the options and to figured out a way to make it even more useful.

Terminal & man pages

I don’t want you to be nervous about trying this because you literally can’t break anything with it, but to play along you have to open the Terminal app on your Mac. If you’ve not played in the Terminal before, it’s inside the Utilities folder inside your Applications folder.

The utility we’re going to use is called screencapture, lowercase, all one word. In the Terminal, you can get the manual for any command by typing man followed by the name of the command. As a general rule, in my many years of messing around in the Terminal, I find the man pages for most Terminal commands to be nearly unintelligible gibberish. Occasionally I get lucky and can suss out a setting here and there but often I don’t have the slightest idea what the manual is trying to tell me.

Luckily, screencapture is the exception to the rule. So let’s type man screencapture into the Terminal. At the top, you’ll see the name of the utility and a description that’s pretty obvious. The next line will look like nonsense. It’s called the synopsis and it says screencapture [-SWCTMPcimswxto] file. Well that’s really clear, right?

Fun with Flags

With command-line utilities, you type the name of a command and then you add flags to specify how you want the command to work. The gibberish inside of the square brackets is all of the possible flags you might want to apply to this command. The list of flags starts with a dash because flags in the Terminal are always preceded by a dash. After the list of flags, it says file and that’s telling you you’ll have the option to save your screen capture to a file by giving it a name.

Now let’s play with the flags. Below the synopsis, there’s a section for Description, and surprisingly it says “The screencapture utility is not very well documented to date. A list of options follows.” I thought that was funny since the documentation is one of the most readable of any Terminal command I’ve used! Maybe because the tool is just so simple, that’s why I can understand the documentation!

The description section lists each flag along with a short description of what it does. Let’s start with the very first flag, which says:

-c force screen capture to go to the clipboard

Let’s see how this works. Open another Terminal window (command-N) so we can keep the man page up in the original window. In the new Terminal window, simply type:

screencapture -c

The Terminal will bring you back to the normal prompt and look like nothing happened. That’s because the screenshot you just took is in your clipboard. Open an app into which you can paste an image, such as Mail, and paste in the image. You should see a screenshot of your entire screen.

If you’re anything like me, that’s absolutely never what I want. I normally want either an area or a single window. Let’s take a look at our list of flags and find one that allows us to capture a selection. If your window for the Terminal isn’t very tall, you may see a colon at the bottom of the screen. This is telling you that there’s more to see in the manual. Just hit the space bar until you see (END) and then you can scroll up and down to see the entire list of flags.

The -i flag is for interactive capture. By default, the -i flag will allow you to select a region on the screen instead of capturing the entire screen. When using flags in Terminal commands, you can combine them after the dash, so to capture an area to the clipboard we can put the c and i together into one command:

screencapture -ci

This time, you should see crosshairs allowing you to capture a section of the screen and paste the resulting screenshot. The man page explains that in interactive mode, you can tap the spacebar to capture a window instead of an area, just like you can if you use the GUI.

If you like interactive mode, but you want the default to capture a window, then use the -W (capital W) flag:

screencapture -cW

If you want to force it to only capture a window instead of allowing any interaction use the -w (lower case) flag:

screencapture -cw

So far this has been fun, but a bit more work than using the keystroke command-control-shift-4, especially if you don’t keep the Terminal open all the time normally. So let’s see if there are things the Terminal command screencapture can do that we can’t easily do otherwise.

Unique Flags

I very often want to send a screenshot via email to the developer of an application to identify where I’m having a problem with their app. With the Terminal command we can take a screenshot that automatically launches Mail.app, starts a new email, and drops the screenshot in, all in one step. From the man page we can see that the flag for this is -M and note this is a capital M. Since we still want to capture just a portion of the screen, we’ll add the -i flag. Since the -M flag is going to paste into an email for you, you don’t have to specify that you want the screenshot to go to the clipboard:

screencapture -Mi

I think that’s really slick and I don’t know another way to do that particular trick with any other app. Remember you can mix and match your flags so if you want a window capture to go straight to mail:

screencapture -Mw

It’s not uncommon for me to want to mark up a screenshot before taking further action, and the easiest place to do that is inside Preview. If you want your screenshot to open in Preview, use the -P flag (note that’s a capital P).

screencapture -ciP

By default, macOS adds a shadow around window screenshots. If you’d rather not have a shadow, simply add the -o flag to your window screenshot. Putting all these pieces together, to

screencapture -oiP

As a bonus tip, if you dislike the giant shadow on screenshots in macOS as much as I do, there is a command to disable it for both the command line and the GUI interface for screencapture:

defaults write com.apple.screencapture disable-shadow -bool true

To make the command take effect, you also need to restart the System UI server:

killall SystemUIServer

Another trick that screencapture has up its sleeve is the ability to capture the screen of your Touch Bar. I know, Touch Bar isn’t as useful as we all hoped it would be but it’s still a fun party trick to be able to capture it if you do find a use for Touch Bar. The flag for capturing Touch Bar is -b:

screencapture -bc

So far I’ve been imposing my own preference for only capturing to the clipboard instead of to a file, so let’s rectify that now. Remember when we talked about the synopsis at the beginning and it had the word file in the command string? To save your screenshot to a file don’t use the -c flag, instead, add a file name with its full path to the end of your command. Let’s just do a simple interactive screenshot to the desktop:

screencapture -i ~/Desktop/deleteme.png

Note that if you use this command repeatedly and don’t change the file name, it will overwrite your original file without asking if that’s what you want or even adding a -1 to the end. This might be a good thing because you won’t get 17 deleteme.png versions sprinkled all over your desktop, or it might be a very bad thing if you think you took 17 separate shots and you discover you have only one.

There are more flags I want to tell you about but I bet many of you are thinking that while this is pretty cool, it’s awfully inconvenient to have to open a Terminal, remember the flags you like, and then type it all into the Terminal window.

Adding screencapture to Keyboard Maestro

After Helma and I played around with these commands a bit, I said exactly that to her, that it’s fun but a lot more work than using a keystroke. That’s when she suggested we figure out how to put these options into Keyboard Maestro so we could assign keystrokes to them.

Now you’re thinking I’ve just taken you in a circle – if we already have keyboard shortcuts for taking screenshots, what good is starting at the command line and creating keystrokes with Keyboard Maestro?

What if I told you that with Keyboard Maestro you could trigger any of your favorite options with the same keyboard shortcut? You’d only need remember that one shortcut instead of a plethora of finger-straining options. Let’s walk through the simple method Helma figured out that will give you this dream world I’ve described.

In Keyboard Maestro you can set up groups of macros, so I created one entitled Terminal. These macros won’t run just inside Terminal since they require interaction with other apps, but it seemed cleaner to collect them in one place.

To create a macro with a Terminal command inside it is super easy. Create a new macro, give it a name, search for the Action called “Execute Shell Script” and drag it in. Then in the text field, plop in the Terminal command.

As an example, I created one called “Clipboard – Screencapture Area” and in the shell script text area I entered screencapture -coi.

For the trigger, I chose hotkey, and mashed down all the keys I could reach – shift-control-option-command and hit the letter T for Terminal. Now if I hit that keystroke (which you will note is much harder than the built-in keystroke), I get crosshairs, I take my screencapture and I’ve got a shadowless capture in my clipboard.

That was easy. Let’s make a second macro. I really like the screenshot to Mail option from the terminal, so following the same process I named this second one “Mail – Screencapture Area”. I repeated it one more time and made one entitled “Preview – Screencapture Area” using screencapture -coiP. I gave both of these macros the exact same keystroke as my original clipboard macro – shift-control-option-command-T.

You’ll notice that I started the title of each of my macros with the name of the thing I was capturing: Clipboard, Mail, and Preview. This is no accident, they are named purposely to start with different letters, and here’s why.

In Keyboard Maestro if you give more than one macro the same hotkey trigger, it needs to know which one you mean when you use that hotkey combination. When this happens, it brings up what’s called the Conflict Palette. This is a tiny little popup window that shows you all of the macros you have that use the same trigger. You can use your mouse to select the one you want. Or if you find it inefficient to move your hands away from the keyboard, you can simply type the first letter of the desired macro to execute it.

That took me WAY more time for me to explain than to use. I mash down all the keys with the T, and then I can hit C for Clipboard, M for Mail, or P for Preview and boom I’m taking the screenshot and sending it exactly where I want it.

Once I had these first three made, I added a comment section to each macro to inform future me on what the script does. I called it “Flags Explained”. I know for a fact that I will never remember what -coiP means! I even got tricky and changed the font to monospaced so it’s easier to read, and made the comments a nice orange color so they stand out.

Another advantage of putting these commands in Keyboard Maestro is that over time I can mutate these macros as I learn more about what I like and I don’t have to learn any new keyboard shortcuts.

More Options to Explore

I’m not going to go through all of the options in screencapture but let me just let you know about a few more that are likely to be useful. You can create timed screenshots, have the GUI screenshot options show on-screen (like if you hit command-shift-5), capture specific windowids, disable sounds during screen captures, and capture rectangles on-screen using coordinates if you’re of that persuasion.

You can also capture video of your screen including an audio track and even have it show mouse clicks. I wasn’t enamored with this option because as far as I could figure out, it only allowed you to capture your entire screen, not a user-specified area or window. With the giant high-resolution screens that are more common nowadays, that will create a huge file with information that’s not helpful to whatever it is we’re trying to demonstrate.

I thought it might be fun to be able to take screenshots that were plopped into apps I use often, like the way Mail is built into the command, so in Keyboard Maestro I added a block to activate Telegram and another block to type the keystroke command-v to paste. It works great!

One last comment about command-line utilities. I said you can string the flags all after one - but that’s not always true. If a command doesn’t work, see if maybe one of the flags needs to stand alone. For example, if you want to force the file type, you use -t, but that flag must be alone right before you specify the file type (in all capital letters). Here’s an example of an interactive screencapture without a shadow that will open in Preview and I’m forcing it to create a PNG:

screencapture -oiP -t PNG

Bottom Line

I said at the beginning that I’m not sure I’ll stick with this method of doing screenshots, but only having one keystroke to memorize and having at my fingertips screenshot methods that are tailored to exactly the way I like them might be enough to make me give up my muscle-memory keystrokes and only use just one. In any case though, I had great fun with Helma on this and you can seriously lose many hours playing with all the different options! Many thanks to J.F for telling me about it and Helma for being my partner in crime.