{"id":23549,"date":"2021-05-07T14:27:38","date_gmt":"2021-05-07T21:27:38","guid":{"rendered":"https:\/\/www.podfeet.com\/blog\/?p=23549"},"modified":"2021-05-09T18:03:05","modified_gmt":"2021-05-10T01:03:05","slug":"screencapture-command-line","status":"publish","type":"post","link":"https:\/\/www.podfeet.com\/blog\/2021\/05\/screencapture-command-line\/","title":{"rendered":"Let Me Try to Convince You to Take Screenshots from the Command Line in macOS"},"content":{"rendered":"
\"Terminal
Terminal `man screencapture`<\/figcaption><\/figure>\n

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\u2019ve talked about macOS\u2019s built-in screen capture, Loom, Capto, Monosnap, Teampaper Snap, Parallels Toolbox, Folge, and the now deprecated Clarify and Stepshot Guides. And yet, I\u2019m hear to tell you about yet another way to take screenshots on macOS.<\/p>\n

This new method is definitely nerdy and yet not super hard nerdy. Whether it\u2019s actually useful and a method even I\u2019ll 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.<\/p>\n

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!<\/p>\n

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.<\/p>\n

Terminal & man pages<\/code><\/h4>\n

I don\u2019t want you to be nervous about trying this because you literally can\u2019t break anything with it, but to play along you have to open the Terminal app on your Mac. If you\u2019ve not played in the Terminal before, it\u2019s inside the Utilities folder inside your Applications folder.<\/p>\n

The utility we\u2019re going to use is called screencapture<\/code>, lowercase, all one word. In the Terminal, you can get the manual for any command by typing man<\/code> 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<\/code> 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\u2019t have the slightest idea what the manual is trying to tell me.<\/p>\n

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

Fun with Flags<\/h4>\n
\"Synopsis
Synopsis of `screencapture` Command<\/figcaption><\/figure>\n

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<\/code> and that\u2019s telling you you\u2019ll have the option to save your screen capture to a file by giving it a name.<\/p>\n

Now let\u2019s play with the flags. Below the synopsis, there\u2019s a section for Description, and surprisingly it says \u201cThe screencapture utility is not very well documented to date. A list of options follows.\u201d I thought that was funny since the documentation is one of the most readable of any Terminal command I\u2019ve used! Maybe because the tool is just so simple, that\u2019s why I can understand the documentation!<\/p>\n

The description section lists each flag along with a short description of what it does. Let\u2019s start with the very first flag, which says:<\/p>\n

-c force screen capture to go to the clipboard<\/code><\/p>\n

Let\u2019s see how this works. Open another Terminal window (command-N) so we can keep the man<\/code> page up in the original window. In the new Terminal window, simply type:<\/p>\n

screencapture -c<\/code><\/p>\n

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.<\/p>\n

If you\u2019re anything like me, that\u2019s absolutely never what I want. I normally want either an area or a single window. Let\u2019s 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\u2019t very tall, you may see a colon at the bottom of the screen. This is telling you that there\u2019s more to see in the manual. Just hit the space bar until you see (END)<\/code> and then you can scroll up and down to see the entire list of flags.<\/p>\n

The -i<\/code> flag is for interactive capture. By default, the -i<\/code> 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<\/code> and i<\/code> together into one command:<\/p>\n

screencapture -ci<\/code><\/p>\n

This time, you should see crosshairs allowing you to capture a section of the screen and paste the resulting screenshot. The man page<\/code> 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.<\/p>\n

If you like interactive mode, but you want the default to capture a window, then use the -W<\/code> (capital W) flag:<\/p>\n

screencapture -cW<\/code><\/p>\n

If you want to force<\/em> it to only capture a window instead of allowing any interaction use the -w<\/code> (lower case) flag:<\/p>\n

screencapture -cw<\/code><\/p>\n

So far this has been fun, but a bit more work than using the keystroke command-control-shift-4, especially if you don\u2019t keep the Terminal open all the time normally. So let\u2019s see if there are things the Terminal command screencapture<\/code> can do that we can\u2019t easily do otherwise.<\/p>\n

Unique Flags<\/h4>\n

I very often want to send a screenshot via email to the developer of an application to identify where I\u2019m 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<\/code> we can see that the flag for this is -M<\/code> and note this is a capital M. Since we still want to capture just a portion of the screen, we\u2019ll add the -i<\/code> flag. Since the -M<\/code> 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:<\/p>\n

screencapture -Mi<\/code><\/p>\n

I think that\u2019s really slick and I don\u2019t 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:<\/p>\n

screencapture -Mw<\/code><\/p>\n

It\u2019s 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<\/code> flag (note that\u2019s a capital P).<\/p>\n

screencapture -ciP<\/code><\/p>\n

By default, macOS adds a shadow around window screenshots. If you\u2019d rather not have a shadow, simply add the -o<\/code> flag to your window screenshot. Putting all these pieces together, to<\/p>\n

screencapture -oiP<\/code><\/p>\n

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:<\/p>\n

defaults write com.apple.screencapture disable-shadow -bool true<\/code><\/p>\n

To make the command take effect, you also need to restart the System UI server:<\/p>\n

killall SystemUIServer<\/code><\/p>\n

Another trick that screencapture has up its sleeve is the ability to capture the screen of your Touch Bar. I know, Touch Bar isn\u2019t as useful as we all hoped it would be but it\u2019s 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<\/code>:<\/p>\n

screencapture -bc<\/code><\/p>\n

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

screencapture -i ~\/Desktop\/deleteme.png<\/code><\/p>\n

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\u2019s what you want or even adding a -1 to the end. This might be a good thing because you won\u2019t 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.<\/p>\n

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.<\/p>\n

Adding screencapture<\/code> to Keyboard Maestro<\/h3>\n
\"Clipboard
Clipboard Macro `screencapture` in Keyboard Maestro<\/figcaption><\/figure>\n

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

Now you\u2019re thinking I\u2019ve just taken you in a circle – if we already have<\/em> keyboard shortcuts for taking screenshots, what good is starting at the command line and creating keystrokes with Keyboard Maestro?<\/p>\n

What if I told you that with Keyboard Maestro you could trigger any of your favorite options with the same<\/em> 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.<\/p>\n

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

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 \u201cExecute Shell Script\u201d and drag it in. Then in the text field, plop in the Terminal command.<\/p>\n

As an example, I created one called \u201cClipboard – Screencapture Area\u201d and in the shell script text area I entered screencapture -coi<\/code>.<\/p>\n

\"Mail
Mail Macro `screencapture` with Comments in Keyboard Maestro<\/figcaption><\/figure>\n

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\u2019ve got a shadowless capture in my clipboard.<\/p>\n

That was easy. Let\u2019s 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 \u201cMail – Screencapture Area\u201d. I repeated it one more time and made one entitled \u201cPreview – Screencapture Area\u201d using screencapture -coiP<\/code>. I gave both of these macros the exact same keystroke as my original clipboard macro – shift-control-option-command-T.<\/p>\n

You\u2019ll 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\u2019s why.<\/p>\n

\"Keyboard
Keyboard Maestro Conflict Palette<\/figcaption><\/figure>\n

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\u2019s 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.<\/p>\n

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\u2019m taking the screenshot and sending it exactly where I want it.<\/p>\n

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 \u201cFlags Explained\u201d. I know for a fact that I will never remember what -coiP<\/code> means! I even got tricky and changed the font to monospaced so it\u2019s easier to read, and made the comments a nice orange color so they stand out.<\/p>\n

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.<\/p>\n

More Options to Explore<\/h3>\n

I’m not going to go through all of the options in screencapture<\/code> 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 windowid<\/code>s, disable sounds during screen captures, and capture rectangles on-screen using coordinates if you\u2019re of that persuasion.<\/p>\n

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.<\/p>\n

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!<\/p>\n

One last comment about command-line utilities. I said you can string the flags all after one -<\/code> 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<\/code>, 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:<\/p>\n

screencapture -oiP -t PNG<\/code><\/p>\n

Bottom Line<\/h3>\n

I said at the beginning that I\u2019m not sure I\u2019ll 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.<\/p>\n","protected":false},"excerpt":{"rendered":"

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\u2019ve talked about macOS\u2019s built-in screen capture, Loom, Capto, Monosnap, Teampaper Snap, Parallels Toolbox, Folge, and the now deprecated Clarify and Stepshot Guides. And […]<\/p>\n","protected":false},"author":1,"featured_media":23552,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[147],"tags":[230,1830,2340,4591,2286,229],"class_list":["post-23549","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-posts","tag-command-line","tag-keyboard-maestro","tag-keyboard-shortcut","tag-screencapture","tag-screenshot","tag-terminal"],"jetpack_featured_media_url":"https:\/\/www.podfeet.com\/blog\/wp-content\/uploads\/2021\/05\/macOSTerminal-Icon.jpg","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/23549","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/comments?post=23549"}],"version-history":[{"count":6,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/23549\/revisions"}],"predecessor-version":[{"id":23564,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/posts\/23549\/revisions\/23564"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/media\/23552"}],"wp:attachment":[{"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/media?parent=23549"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/categories?post=23549"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.podfeet.com\/blog\/wp-json\/wp\/v2\/tags?post=23549"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}