macOS Terminal Icon

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

Terminal man screencapture
Terminal `man screencapture`

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

Synopsis of `screencapture` Command
Synopsis of `screencapture` Command

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

Clipboard Macro `screencapture` in Keyboard Maestro
Clipboard Macro `screencapture` in 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.

Mail screencapture with Comments in Keyboard Maestro
Mail Macro `screencapture` with Comments in Keyboard Maestro

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.

Keyboard Maestro Conflict Palette
Keyboard Maestro Conflict Palette

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.

18 thoughts on “Let Me Try to Convince You to Take Screenshots from the Command Line in macOS

  1. Tim McCoy - May 8, 2021

    I am using zsh now and I have created two aliases to turn the shadows off and on:
    alias — shadowon=’defaults write com.apple.screencapture disable-shadow -bool false && killall SystemUIServer’
    alias — shadowoff=’defaults write com.apple.screencapture disable-shadow -bool true && killall SystemUIServer’

    BTW, I believe your command example to do that should turn the shadow ON – not off.
    e.g.; “do you want to disable-shadow? ‘no'” == false/0 ON
    “do you want to disable-shadow? ‘yes'” == true/1 OFF

    Curiously, I cannot get this to work with the more familiar (and easier for me) ⇧⌘4, BUT it does work with ⇧⌘5.
    I did not test ⇧⌘3 or any ‘⌃⇧⌘ number sequences.

  2. podfeet - May 8, 2021

    Tim – very cool. You’re right – I had the defaults write backward! I’ve fixed it now.

    On shift-command-4, the shadow only appears if it’s a window screenshot, not a defined area screenshot. Maybe that’s why you don’t see the different behavior?

  3. Bob - May 11, 2021

    I’ve been wanting to do something like this to automate the recording of our local news and other sources that use odd video formats. I tried this:

    screencapture -v ~/Desktop/screenrecording.mov

    and it works fine, but in order to record for a set length of time, I tried this and it didn’t work:

    screencapture -v ~/Desktop/screenrecording.mov -V 10

    It gave me the same message as the first one: “enter any character (or ctrl-c) to stop screen recording”. The manual shows: -V Capture video recording of the screen for the specified seconds. So I’m not sure why that’s not working.

  4. Tim McCoy - May 11, 2021

    Bob, I have seen the same message and problem capturing part of the screen.
    My syntax: % screencapture -T 10 -R 168,411,1440,810 -v ~/Desktop/screenrecording.mov -V 10 -d -g

    enter any character (or ctrl-c) to stop screen recording
    2021-05-11 16:59:41.566 screencapture[30005:733332] Error loading /Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL: dlopen(/Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL, 0x0106): code signature in (/Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL) not valid for use in process: mapping process is a platform binary, but mapped file is not
    ^Cgot ctrl-c

    But I get this Xcode invalid signature and no sound. Just bee chatting with Apple support we will see…

  5. Anonymous - May 11, 2021

    I got a similar message and had to delete the iGlasses app so I’m thinking you have some camera-related app that is interfering. Also, this is working for me:

    screencapture -V 10 -g -R 100,50,500,300 -v ~/Desktop/screenrecording.mov

  6. Bob Cassidy - May 11, 2021

    Tim, in your command:

    screencapture -T 10 -R 168,411,1440,810 -v ~/Desktop/screenrecording.mov -V 10 -d -g

    what is -T and -d. I don”t see those in the man page.

  7. Tim McCoy - May 11, 2021

    Bob, -T == delay 10 seconds before starting. -d == display errors to user graphically. -g == capture audio during video recording.

    All on the man pages.

    After upgrading MacOS and reinstalling Xcode it still fails for me. Same error messages, no sound. ^c still required.

  8. Tim McCoy - May 11, 2021

    Odd, I just moved -g to the very front of my syntax and got sound, but still the error remains. ^c still stops.
    screencapture -g -T 10 -R 168,411,1440,810 -v ~/Desktop/screenrecording.mov -V 10

    BTW it is not very good sound, but I finally got some. Sound output is to headphone jack to external speakers; gonna disconnect that and try again… Not much if any better. Now to put the audio through soundflower… No sound. Back to speakers sound like a tunnel version.

  9. podfeet - May 12, 2021

    I wish I understood why, but reordering things definitely helps. This order captured a 10-second video after waiting 2 seconds and required no user intervention to stop.

    `screencapture -gv -T 2 -R 168,411,1440,810 -V 10 ~/Desktop/screenrecording.mov`

    On audio, it’s using your default audio input, so check that? In system sound input, I chose my big girl mic first, and it sounded kind of hollow, so then I chose my Audio Hijack-sweetened audio that I use for the podcast and it definitely changed to the better audio.

  10. Bob Cassidy - May 12, 2021

    This is working great for me, with a few caveats:

    ScreenCapture -V 5 -g -R 0,295,780,445 -v ~/Desktop/screenrecording.mov

    To get audio, I have to use Rogue Amoeba’s Loopback. Sounds like Tim’s audio may be coming from the speakers and recorded through the microphone. Loopback lets you record the sound directly from an app. There are free ways to do that and I’ve tried many of them, but Loopback is WAY easier. Check here for Allison’s blog post about Loopback: https://www.podfeet.com/blog/2020/06/loopback/

    I also had a similar error message to Tim’s “Error loading /Library/” error and found I had to delete Ecamm’s iGlasses. In your case it looks like the conflict is the DisableCameraDAL.plugin which seems to be part of Parallels Toolbox: https://forum.parallels.com/threads/disablecameradal-plugin-cant-be-opened-catalina.348589/

    Another weirdness is that when I try to use that same ScreenCapture command in a Keyboard Maestro Shell Script, it doesn’t work and fails with this cryptic error message:

    Execute a Shell Script failed with script error: text-script: line 1: 18199 Abort trap: 6. ScreenCapture -V 5 -g -R 0,290,720,410 -v ~/Desktop/screenrecording.mov. Macro “Trying” cancelled (while executing Execute Shell Script)

    But if I have KM open Terminal and paste the command, it works fine! I narrowed it down to -g. If I remove that it works fine in a shell script, but then there’s no audio.

    In any case, being able to record screen videos in the terminal through KM is going to help me out a lot.

  11. Tim McCoy - May 12, 2021

    Finally have sound like I needed it, using Soundflower! Had to switch to Soundflower (2 Chanel) for BOTH input and output. I have used Soundflower with Garageband in the past to capture system audio; I thought I would revisit the sound preferences and finally thought I should have all IO use Soundflower. Borrowing all that everyone has provided I also chose a longer video time. Worked great!

    BigSur: [1321]% screencapture -gv -T 10 -V 30 -R 168,411,1440,810 ~/Desktop/screenrecording.mov

    I still get the error message at the moment, but I no longer have to use ^C to end it. Sweet; my thanks to all

    2021-05-12 15:34:53.993 screencapture[11555:400961] Error loading /Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL: dlopen(/Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL, 0x0106): code signature in (/Library/CoreMediaIO/Plug-Ins/DAL/!DisableCameraDAL.plugin/Contents/MacOS/!DisableCameraDAL) not valid for use in process: mapping process is a platform binary, but mapped file is not

  12. Bob Cassidy - May 12, 2021

    Tim, you should try uninstalling Parallels Toolbox to see if that error message goes away.

  13. Allison Sheridan - May 12, 2021

    Like others here, Tim, I also had to delete a virtual camera to stop the errors. Mine was the Snap Camera.

    I don’t think you need to disable Parallels Toolbox. It looks like the app in Parallels Toolbox is the “Block Camera” tool. Try turning just that tool off and see if that clears the error.

    If that doesn’t work you can disable the plugin by these instructions from Parallels:

    1. Make sure that “Block Camera” tool is turned ON (the tool should be highlighted inside Parallels Toolbox).
    2. Open Toolbox window.
    3. Click on “Block Camera” tool with pressed “Option ⌥” key. The tool will ask password and remove it’s plugin.
    4. Restart macOS.

  14. Tim McCoy - May 13, 2021

    Thanks Bob, but I tried parallels years ago and abandoned it, long gone. But I found vestiges of it remained. Now deleted, I still get the error which does not mention “parallels” at all.

    BTW, still looking for some kind of terminal/automator syntax to auto magically change audio I/O sources to make screencapture do what I want, when I want, easily.

  15. Tim McCoy - May 13, 2021

    Allison, I missed your note until I refreshed my screen for that message to Bob.

    Now I have found the way to have soundflower capture system and microphone by creating an aggregate device. I found the method on this YouTube video: https://www.youtube.com/watch?v=U-5qxNeMl7E (guy goes too fast had to pause several times)

    Now I no longer have to find a way to turn soundflower on or off for normal speakers. Now I can work on automating just the screen capture and not worry about sound.

  16. podfeet - May 13, 2021

    Soundflower has been unsupported for many years. Check out the currently-supported, open source alternative, BlackHole: https://github.com/ExistentialAudio/BlackHole or https://existential.audio/blackhole/

    Says there’s a Windows version too.

  17. Bob Cassidy - May 13, 2021

    Allison, I’ve used blackhole and other free methods successfully, but Loopback is soooooo much easier. I know, I know, it’s expensive, but it was so worth it. Those Rogue Amoeba guys are amazing. BTW, love your podcasts.

  18. podfeet - May 13, 2021

    Awe, thanks, Bob! I’m 100% with you on Loopback vs. Blackhole or the deprecated Soundflower. But I’d rather someone use Blackhole than unsupported software.

    So Tim – buy Loopback! It’s the BEST! but if not, can I interest you in the open source, supported Blackhole?

Leave a Reply

Your email address will not be published.

Scroll to top