The wacdum:// URL scheme
Anything on your Mac that can open a URL can drive Wacdum. That covers Shortcuts, Raycast, Alfred, Keyboard Maestro, Stream Deck, BetterTouchTool, Automator, a shell script, or a link in a document. There are 22 commands, and they all follow the same shape.
open "wacdum://capture-area?action=upload"How it works
A command is the part after the scheme, and parameters are an ordinary query string. Wacdum does not need to be in the foreground, and opening a URL does not bring it forward: the capture overlay takes over without disturbing the window you are trying to shoot.
Wacdum has to be running for a URL to do anything, which it is by default since it lives in the menu bar. A command it does not recognise is written to the log rather than swallowed, so a typo in a script is something you can find.
Both wacdum://capture-area and wacdum:///capture-area work, because people write the slash out of habit.
In Shortcuts, use the Open URLs action. In Raycast or Alfred, a Script Filter or a shell command running open. In a Stream Deck profile, the Websiteaction with “Access in background” switched on.
Taking a screenshot
Every command here accepts action, so a script can decide what happens to the shot rather than inheriting whatever the app is set to. Give an area and there is no picker at all: the capture happens immediately.
wacdum://all-in-one
Opens the All-in-One frame, where you pick the mode after framing the area: still, fullscreen, window, scrolling, timer, text, video or GIF.
open "wacdum://all-in-one"Parameters: x, y, width, height, display, origin
wacdum://capture-area
Captures a region. With an area given it fires straight away, otherwise it opens the picker.
open "wacdum://capture-area?x=0&y=0&width=1280&height=720&action=upload"Parameters: action, x, y, width, height, display, origin
Also accepts: wacdum://capture-region
wacdum://capture-fullscreen
Captures whole screens. With no display it captures every screen, the same as the menu command. With display given it captures exactly that one.
open "wacdum://capture-fullscreen?display=2&action=copy"Parameters: action, display
Also accepts: wacdum://capture-screen
wacdum://capture-window
Opens the window picker, then captures the window you click.
open "wacdum://capture-window?action=annotate"Parameters: action
wacdum://capture-previous-area
Re-captures the last area you framed, with no picker. The one to bind when you are documenting the same window over and over.
open "wacdum://capture-previous-area?action=pin"Parameters: action
wacdum://self-timer
Counts down, then captures. Useful for menus and hover states that close the moment you touch anything else.
open "wacdum://self-timer?seconds=10&action=save"Parameters: action, seconds, x, y, width, height, display, origin
wacdum://scrolling-capture
Follows an area while the page scrolls and stitches what is revealed into one tall image.
open "wacdum://scrolling-capture?x=100&y=100&width=900&height=600"Parameters: action, x, y, width, height, display, origin
wacdum://capture-text
Reads the text out of an area, or out of an image you already have, and copies it. Opens a window so you can check the recognition before you paste.
open "wacdum://capture-text?filepath=~/Desktop/invoice.png"Parameters: filepath, x, y, width, height, display, origin
Also accepts: wacdum://ocr
Recording
Recording commands start immediately when you give them an area. A second capture request while a recording is running stops it, so one shortcut can serve as both.
wacdum://record-screen
Records a whole screen, or the area you give.
open "wacdum://record-screen?display=1"Parameters: x, y, width, height, display, origin
wacdum://record-area
Records a region. Without an area it opens the picker first.
open "wacdum://record-area?x=0&y=0&width=1280&height=720"Parameters: x, y, width, height, display, origin
Also accepts: wacdum://record-region
wacdum://record-gif
Records straight to an animated GIF instead of a video file.
open "wacdum://record-gif"Parameters: x, y, width, height, display, origin
wacdum://stop-recording
Stops the recording in progress and hands it to the capture card.
open "wacdum://stop-recording"Working with images you already have
These take a capture you made earlier, or something from another app, and put it into Wacdum. Your original file is never modified.
wacdum://open-annotate
Opens an image in the annotation editor. With no path it asks you to choose a file.
open "wacdum://open-annotate?filepath=~/Desktop/shot.png"Parameters: filepath
Also accepts: wacdum://open, wacdum://annotate
wacdum://open-from-clipboard
Opens whatever image is on your clipboard in the annotation editor. Tells you when there is nothing usable there.
open "wacdum://open-from-clipboard"wacdum://pin
Pins an image on top of everything as a floating window, so you can keep a reference in view while you work.
open "wacdum://pin?filepath=~/Desktop/shot.png"Parameters: filepath
wacdum://add-quick-access-overlay
Puts an image on the capture card, so you can copy, save, upload, annotate or pin it through the normal flow.
open "wacdum://add-quick-access-overlay?filepath=~/Desktop/shot.png"Parameters: filepath
Windows and settings
Opening the parts of the app you would otherwise reach through the menu bar.
wacdum://open-history
Opens Capture History, every capture this Mac has taken.
open "wacdum://open-history"Also accepts: wacdum://history
wacdum://restore-recently-closed
Brings back the capture card you just dismissed. The undo for a mis-clicked discard.
open "wacdum://restore-recently-closed"Also accepts: wacdum://restore-last-closed-card
wacdum://open-settings
Opens Settings, on a named tab if you give one.
open "wacdum://open-settings?tab=cloud"Parameters: tab
Also accepts: wacdum://settings
Desktop icons
These change Finder's own setting and restart the Finder to apply it, so the change sticks until you change it back. A request that would make no difference is skipped rather than bouncing the Finder for nothing.
wacdum://hide-desktop-icons
Hides the icons on your desktop.
open "wacdum://hide-desktop-icons"wacdum://show-desktop-icons
Puts them back.
open "wacdum://show-desktop-icons"wacdum://toggle-desktop-icons
Flips whichever way they currently are.
open "wacdum://toggle-desktop-icons"Parameters
Shared across commands. Anything a command does not read is ignored, so you can keep one URL template and change only the command name.
- actioncopy | save | annotate | upload | pin
- What happens to the capture once it exists. This overrides both the capture card and your After capture rule for that one capture, and does not change your settings. Leave it out to get your normal behaviour.
- x, ypixels
- Top left corner of the area, measured from the top left of the display. Add origin=bottom-left to measure from the bottom instead.
- width, heightpixels
- Size of the area. Both are required for an area to be used at all, and both must be at least 4. Without them the command falls back to asking you to drag a box.
- display1, 2, 3 …
- Which screen the coordinates belong to. 1 is your main display. An index you do not have falls back to the main display rather than failing, so a script written while docked still runs on the road.
- origintop-left | bottom-left
- Which corner x and y are measured from. Defaults to top-left. Set bottom-left if the coordinates you already have are measured from the bottom of the screen.
- filepathan absolute path
- A file on disk. A leading file:// and a leading ~ are both accepted. path is accepted as a synonym.
- seconds5 | 10
- Countdown for the self timer. The app rounds to the nearest delay it supports and puts your own setting back afterwards.
- tabgeneral | wallpaper | shortcuts | quickaccess (or overlay) | recording | screenshots | cloud | advanced | about
- Which Settings tab to open on. Left out, Settings opens where you last left it.
Older spelling: clipboard=true still works and means the same as action=copy. It was the only option before actions existed, and existing scripts keep running.
Details worth knowing
Small things that decide whether a URL you have written elsewhere runs here unchanged.
- x and y start at the top left
- Some screenshot tooling measures from the bottom left instead. Add origin=bottom-left and your existing numbers work unchanged.
- filepath and path mean the same thing
- Both spellings are accepted everywhere a file is taken, so a URL written either way runs. A leading file:// and a leading ~ are fine too.
- display counts from 1
- display=1 is your main screen. An index you do not have falls back to the main display rather than failing, so a script written while docked still runs on the road.
- Settings tab names
- tab=quickaccess and tab=overlay both open the Quick Access tab. A name Wacdum does not have opens Settings where you left it, and says so in the log.
- Desktop icons stay as you set them
- hide, show and toggle change Finder's own setting, so it survives a restart. A request that would make no difference is skipped rather than bouncing the Finder for nothing.
Where to find this in the app
Settings, then Advanced, under Automation. There is a button there that copies every command with its parameters, so you have the list to hand without leaving the app.