How to Use BetterShot: A Complete Guide to macOS Screenshot, Screen Recording & Automation Workflows

Stop Paying Monthly for CleanShot X: Handle macOS Screenshots, Screen Recording & Automation with This Open Source Tool

When creating technical documentation, writing product reviews, or reproducing a bug for colleagues, you've probably experienced this awkward situation: the built-in screenshot tool only captures static images, switching to QuickTime for screen recording, then opening Preview or Final Cut to add arrows or crop unnecessary parts... After jumping between tools for half an hour, you haven't even started writing what you actually need to.

As a backend developer who has used macOS for years, I know this pain all too well. Then I discovered BetterShot—an open-source tool built with native SwiftUI, boasting 2,300+ stars and positioning itself as an alternative to CleanShot X and Loom. After using it for nearly two weeks, I'll guide you from zero to running it smoothly, then build a "one-click screenshot auto-upload" workflow using URL schemes. After mastering this flow, you'll handle everything from capture to editing to sharing in a single window.

Prerequisites

• Operating System: macOS 26.0 or later (If you're on an older version, the project README also provides a direct .dmg download for backward compatibility testing)
• Hardware: Works on both Apple Silicon and Intel Macs. The video editing section uses GPU hardware encoding, which runs smoother with Apple GPU
• Basic Knowledge: Familiarity with Homebrew and Terminal. If compiling from source, you'll also need Xcode 26+ and XcodeGen
• Permissions: On first launch, you'll be prompted to grant Screen Recording, Accessibility, and other permissions. These are system-level requirements that must be allowed

Quick Start: Three Steps to Get Running

Step 1: Installation

The fastest way is a single command:

brew install --cask bettershot

After installation, launch from Launchpad or the Applications folder. On first open, you'll see a three-step onboarding: Welcome → Permissions → First Capture. Just follow through.

If you prefer not to use Homebrew, you can also download the .dmg file from GitHub Releases and drag it to Applications.

Step 2: Learn the Default Shortcuts

BetterShot binds the most common operations to shortcuts. Memorizing a few key ones is enough:

Why are these important? Because all custom shortcuts later are based on the same system. Once you're familiar with the defaults, remapping to your own preferences becomes intuitive. ⌘⇧2 is the core entry point—it brings up a floating panel where you can choose screenshots, screen recording, region recording, and more.

Step 3: Your First Screenshot

Press ⌘⇧4 to enter macOS's native region selection mode. After releasing the mouse, the screenshot won't be dumped directly to your desktop—instead, it appears in BetterShot's Capture Deck (floating stack). This design is clever: screenshots are placed in a private workspace in memory, giving you time to decide whether to copy to colleagues, save locally, or open the editor for annotations.

The Capture Deck holds up to 5 screenshots simultaneously, supporting Copy, Save, Pin, Edit, cloud sharing, and drag-and-drop export. Think of it as a "screenshot staging area"—process before saving to disk, keeping your desktop clutter-free.

Practical Tutorial: Building a "Command-Line Screenshot → Auto-Open Editor → Annotate & Upload to R2" Automation Flow

Now that you know the basics, let's do something interesting—BetterShot supports URL scheme protocol calls, meaning you can trigger its features directly from Alfred, Raycast, or a shell script.

What is a URL scheme?

Simply put, it's a custom protocol. Just like https:// opens a browser, bettershot:// wakes up BetterShot and executes a specific action. Supported protocols include:

• bettershot://capture/region — Trigger region screenshot
• bettershot://capture/fullscreen — Full screen screenshot
• bettershot://record — Start screen recording
• bettershot://ocr — Launch OCR text extraction

Creating a "Quick Screenshot & Enter Edit" Hotkey with Alfred

Assuming you're using Alfred (or Raycast—the principle is the same), you can create a Hotkey trigger linked to the following workflow script:

#!/bin/bash
## Trigger region capture using bettershot URL scheme
open "bettershot://capture/region"

## Wait for capture to complete (~1-2 seconds), then auto-activate editor
sleep 1.5
osascript -e 'tell application "BetterShot" to activate'

This script does two things:

1. Uses open bettershot://capture/region to put BetterShot into region screenshot mode
2. After capture completes, uses AppleScript to bring BetterShot to the foreground, making it easy to click Edit directly in the Capture Deck

Why do this? Native shortcuts already work well, but if you're capturing dozens of screenshots daily for bug reports or technical docs, using a custom hotkey (e.g., ⌥⇧S) with this script skips the panel selection step and goes straight to capture mode, boosting efficiency by at least 30%.

Compiling from Source (Optional)

If you want to modify features or try the latest builds, compile from source:

brew install xcodegen
git clone https://github.com/KartikLabhshetwar/better-shot.git
cd better-shot
make release
open .build/Build/Products/Release/BetterShot.app

Compilation requires macOS 26.0+ and Xcode 26+, implemented in pure Swift + SwiftUI with only one third-party dependency: DockProgress. Run make test to execute all tests, including editor snapshot and export integration tests.

Common Issues / Pitfalls to Avoid

1. Permissions dialog not appearing? If the first launch doesn't prompt for Screen Recording permission, go to "System Settings → Privacy & Security → Screen Recording" and manually add BetterShot, then restart the app.
2. Shortcut conflicts? BetterShot has 75+ customizable shortcuts. The Settings → Shortcuts page automatically detects conflicts. If you're using other tools (like Paste or Shottr), avoid binding the same key combinations.
3. How to configure cloud sharing? BetterShot supports uploading screenshots and videos to your own Cloudflare R2 storage bucket. Fill in Bucket, Endpoint, Access Key, and Secret Key in Settings → Cloud Sharing. Uploads go through your own storage, never touching third-party servers—privacy guaranteed.
4. Video export stuttering? Export uses GPU hardware encoding and accelerators. If your Mac is older or has GPU driver issues, try lowering the frame rate (adjustable from 30fps to 60fps) or switching to MOV format.

Summary

Today we accomplished three things:

1. Installed BetterShot with a single Homebrew command, completed first-run setup and permission configuration
2. Mastered core shortcuts and Capture Deck interaction logic—no more screenshots scattered across your desktop
3. Built an automated screenshot-to-editor workflow using URL schemes + shell scripts

BetterShot is an open source project under the BSD 3-Clause license—no subscription fees, no account system, no telemetry data collection. Screenshots and videos remain entirely on your Mac unless you actively share them. For macOS users who don't want to pay monthly for CleanShot X but need an all-in-one solution for screen recording, editing, and cloud sharing, this is a highly practical choice.

Next Steps:

• Try the video editor: BetterShot's built-in trimming, speed control (0.25x ~ 8x), transitions, cropping, and camera overlay layouts (picture-in-picture, side-by-side, presenter mode, etc.) will click once you record a tutorial video
• If you use Raycast or Hammerspoon, you can write more complex automations based on URL schemes—like running OCR after capture, extracting text, and appending to Notion docs
• Watch project Releases. With 2,300+ stars, the community iterates quickly and new features roll out regularly

Feel free to discuss in the comments or open a GitHub Issue to contribute to the open source project.