Tutorial: macOS Setup
This tutorial walks you through the complete macOS-specific onboarding for Rephlo, from installation through your first drag-select command. If you have already completed the general Installation & Setup, this tutorial covers the macOS details in greater depth.
Purpose
macOS has unique security and privacy requirements that affect how Rephlo operates. Unlike Windows, where global hotkeys work out of the box, macOS requires explicit user consent for Accessibility and Screen Recording. This tutorial ensures you configure everything correctly so that Rephlo's full feature set is available from day one.
Prerequisites
| Requirement | Details |
|---|---|
| macOS Version | 10.15 Catalina or later |
| Architecture | Apple Silicon (M1/M2/M3/M4) or Intel (x64) |
| Disk Space | ~250 MB for the application bundle |
| Ollama (optional) | If you plan to use local models, install Ollama separately |
Step 1: Download and Install
1.1 Download Rephlo
Go to https://rephlo.app/download and download the latest macOS package:
Rephlo-macos-arm64.dmgfor Apple Silicon Macs (M1/M2/M3/M4)Rephlo-macos-x64.dmgfor Intel Macs
1.2 Install to Applications
- Open the downloaded
.dmgfile. - Drag
Rephlo.appinto the/Applicationsfolder. - Eject the disk image.
┌─────────────────────────────────────────────────────────────────────────┐
│ DMG INSTALL WINDOW │
├────────────────────────────────── ───────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ │ ─────────> │ │ │
│ │ Rephlo │ Drag here │ Applications │ │
│ │ .app │ │ folder │ │
│ │ │ │ │ │
│ └──────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
1.3 First Launch — Gatekeeper
The first time you open Rephlo, macOS Gatekeeper may block it with a message: "Rephlo.app cannot be opened because the developer cannot be verified."
To proceed:
- Do not double-click the app. Instead, right-click (or Control-click)
Rephlo.appin/Applications. - Select "Open" from the context menu.
- In the confirmation dialog, click "Open" again.
macOS remembers this choice. Subsequent launches work normally by double-clicking.
Why does this happen? macOS Gatekeeper warns about apps downloaded from outside the Mac App Store. The right-click > Open method bypasses this check for the current app.
Step 2: Grant Required Permissions
Why Permissions Are Needed
Rephlo uses SharpHook (a cross-platform library wrapping macOS CGEventTap) to listen for global hotkeys and monitor text selection across all applications. macOS requires Accessibility permission for any process that creates a CGEventTap. Screen Recording permission is required separately for screenshot capture.
Without these permissions, Rephlo's system-wide integration will not function.
2.1 The PermissionPreCheckDialog
Immediately after the first launch, Rephlo displays the PermissionPreCheckDialog:
┌─────────────────────────────────────────────────────────────────────────┐
│ PERMISSION PRECHECK DIALOG │
├─────────────────────────────── ──────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ Rephlo needs permissions to work properly │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ 1. Accessibility [ ] Granted │ │ │
│ │ │ Global hotkeys and text detection │ │ │
│ │ │ [Open System Settings] │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ 2. Screen Recording [ ] Granted │ │ │
│ │ │ Screenshot capture for visual commands │ │ │
│ │ │ [Open System Settings] │ │ │
│ │ └─────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ [Check Again] [Skip for Now] │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 Grant Accessibility Permission
- In the PermissionPreCheckDialog, click "Open System Settings" next to Accessibility.
- macOS opens System Settings > Privacy & Security > Accessibility.
- Locate Rephlo in the app list.
- Toggle the switch ON.
- If prompted, authenticate with your macOS password or Touch ID.
- Return to the Rephlo dialog.
┌─────────────────────────────────────────────────────────────────────────┐
│ SYSTEM SETTINGS > ACCESSIBILITY │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Privacy & Security > Accessibility │
│ │
│ Allow the apps below to control your computer. │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ App Name Toggle │ │
│ ├─────────────────────────────────────────────────────────────────┤ │
│ │ Terminal [OFF] │ │
│ │ Rephlo [ON] <--- │ │
│ │ ... │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ Click the lock icon to make changes. Authenticate if prompted. │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.3 Grant Screen Recording Permission
- In the PermissionPreCheckDialog, click "Open System Settings" next to Screen Recording.
- macOS opens System Settings > Privacy & Security > Screen Recording.
- Locate Rephlo in the app list.
- Toggle the switch ON.
- Authenticate if prompted.
- Return to the Rephlo dialog.
2.4 Verify and Restart
- Back in the Rephlo dialog, click "Check Again".
- Both permissions should now show as Granted.
- Quit Rephlo completely (right-click the menu bar icon > Exit, or
Cmd+Q). - Relaunch Rephlo from
/Applications. Some macOS permission changes require a full restart to take effect.
Tip: If the checkboxes still show "Not Granted" after toggling the permissions on, try quitting Rephlo, waiting a few seconds, and relaunching. macOS sometimes caches the old permission state.
Step 3: Set Up Your First Provider
With permissions granted, configure an AI provider so Rephlo can process your commands.
- Click the Rephlo icon in the menu bar, then select "Settings" (or open the Dashboard and navigate to Settings).
- Go to Settings > LLM Providers.
- Choose a provider from the list:
| Provider | What You Need |
|---|---|
| OpenAI | API key from platform.openai.com |
| Anthropic | API key from console.anthropic.com |
| API key from aistudio.google.dev | |
| Groq | API key from console.groq.com |
| xAI (Grok) | API key from console.x.ai |
| OpenRouter | API key from openrouter.ai |
| Azure OpenAI | Endpoint URL + API key from your Azure portal |
| Ollama | Local install, no key needed (endpoint: http://localhost:11434) |
| OpenAI-Compatible | Endpoint URL + API key for any compatible service |
- Enter your API Key (and endpoint URL if applicable).
- Click Test Connection to verify.
- Click Save.
Quick start recommendation: If you are new to AI APIs, OpenAI or Anthropic are the most straightforward to set up. If you prefer full privacy with no cloud dependency, install Ollama and use local models.
Step 4: Learn macOS Hotkeys
Rephlo uses platform-specific default hotkeys. Here are the macOS defaults compared to Windows/Linux:
| Action | macOS | Windows / Linux |
|---|---|---|
| Context Menu Overlay | Shift+Cmd+C | Ctrl+Shift+Alt+C |
| Screenshot Capture | Shift+Cmd+S | Ctrl+Shift+Alt+S |
| Drag-Select Modifier | Cmd | Ctrl |
| Zoom In | Cmd+Plus | Ctrl+Plus |
| Zoom Out | Cmd+Minus | Ctrl+Minus |
| Reset Zoom | Cmd+0 | Ctrl+0 |
Customizing Hotkeys
All hotkeys are fully customizable:
- Open Settings > Hotkeys.
- Click the hotkey field you want to change.
- Press your desired key combination.
- Click Save.
Tip: If a hotkey conflicts with another application (e.g., Spotlight, Alfred, or Raycast), choose an alternative combination. Rephlo will warn you if the chosen hotkey is already in use by the system.
Step 5: Test with Drag-Select
The drag-select workflow is the fastest way to use Rephlo on macOS. Let's try it:
5.1 Open Any Text Application
Open TextEdit, Notes, Safari, or any app with selectable text.
5.2 Perform the Drag-Select
- Hold the
Cmdkey (the default drag-select modifier on macOS). - While holding
Cmd, click and drag your mouse across some text to select it. - When you release the mouse button, the Rephlo overlay appears immediately near your cursor.
┌─────────────────────────────────────────────────────────────────────────┐
│ DRAG-SELECT WORKFLOW (macOS) │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Hold Cmd 2. Drag to select 3. Overlay appears │
│ ┌────── ────┐ ┌──────────────────┐ ┌────────────────────┐ │
│ │ │ │ │ │ Active: "Lorem..." │ │
│ │ [Cmd] │ + │ "Lorem ipsum │ ──> ├────────────────────┤ │
│ │ (hold) │ │ dolor sit..." │ │ > Summarize │ │
│ │ │ │ [============] │ │ Fix Grammar │ │
│ └──────────┘ └──────────────────┘ │ Translate │ │
│ └────────────────────┘ │
│ │
│ 4. Click a command to execute it. │
│ 5. Result appears. Copy or Insert back into the original app. │
│ │
└─────────────────────────────────────────────────────────────────────────┘
5.3 Execute a Command
- In the overlay, click "Summarize" (or any command).
- Rephlo sends the selected text to your configured AI provider.
- The result appears in the overlay.
- Click Copy to place the result on your clipboard, or Insert to replace the original text.
Note: The drag-select modifier key is customizable. Go to Settings > Hotkeys > Text Selection Trigger to change it from
Cmdto another key if preferred.
Troubleshooting macOS-Specific Issues
Hotkeys Not Working
Symptom: Pressing Shift+Cmd+C does nothing. The overlay does not appear.
Cause: Accessibility permission is not granted, or the app was not restarted after granting the permission.
Fix:
- Open System Settings > Privacy & Security > Accessibility.
- Confirm Rephlo is toggled ON.
- If it was already on, toggle it OFF, then ON again.
- Quit and relaunch Rephlo.
Screenshot Capture Not Working
Symptom: Screenshot commands fail or produce a blank image.
Cause: Screen Recording permission is not granted.
Fix:
- Open System Settings > Privacy & Security > Screen Recording.
- Confirm Rephlo is toggled ON.
- Quit and relaunch Rephlo.
Overlay Not Appearing
Symptom: You press the hotkey or drag-select, but no overlay window appears.
Possible Causes and Fixes:
| Possible Cause | Fix |
|---|---|
| Accessibility not granted | Grant Accessibility permission and restart |
App not running as .app bundle | Launch from /Applications/Rephlo.app, not via dotnet run |
| Hotkey conflict with another app | Check Settings > Hotkeys for conflicts; change the combination |
| App is paused | Right-click the menu bar icon; if "Resume Rephlo" is shown, click it |
Gatekeeper Blocks the App on Every Launch
Symptom: macOS keeps showing the "developer cannot be verified" warning.
Fix: Ensure you right-clicked and selected "Open" on the first launch. If the issue persists:
- Open System Settings > Privacy & Security.
- Scroll down to the Security section.
- You should see a message about Rephlo being blocked. Click "Open Anyway".
Rephlo Not Visible in Permission Lists
Symptom: You open System Settings > Accessibility but Rephlo is not listed.
Fix: Launch Rephlo at least once. macOS adds apps to permission lists only after the app first attempts to use the protected feature. After launching, check the permission list again.
Next Steps
You are now fully set up on macOS. Here are recommended next steps:
- First Use Walkthrough — Run your first AI command step by step.
- Commands — Learn how to create and customize your own commands.
- Spaces — Add your documents as AI context for grounded responses.
- Template Gallery — Browse pre-built commands for common tasks.
- Advanced Use Cases — Power-user workflows and automation recipes.