Documentation

Everything you need to get started with cmdHalo and master your keyboard shortcuts.

System Requirements

Operating System

macOS 13 (Ventura) or later

Architecture

Apple Silicon & Intel

Disk Space

~15 MB

Permissions

Accessibility (required)

Installation

Download
Purchase and download cmdHalo from Gumroad. You will receive a .dmg file.
Install
Open the DMG and drag cmdHalo into your Applications folder.
Launch
Open cmdHalo from Applications. macOS may ask you to confirm since the app was downloaded from the internet — click Open.

License Activation

When you first open cmdHalo, you will see the activation screen. Enter the license key you received in your Gumroad purchase confirmation email.

License key format

Your key looks like:

XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX

Each license supports activation on up to 2 devices. Your key is validated securely against Gumroad and a signed token is stored locally for offline use (revalidated every 30 days).

Permissions Setup

cmdHalo requires Accessibility permission to detect keyboard shortcuts and display the overlay. Without it, the app cannot function.

After activation, cmdHalo will show the permission onboarding screen and trigger the macOS system dialog.
Go to System Settings → Privacy & Security → Accessibility.
Find cmdHalo in the list and toggle it on.
cmdHalo will detect the change automatically and start immediately.

Tip: If cmdHalo is not in the list, click the + button and select it from your Applications folder. You can also use the “Reveal in Finder” button in the onboarding screen.

How to Use

Hold Mode (default)

Press and hold the trigger key (Command by default) for a moment. The overlay appears showing all available shortcuts for the active application. Release the key to dismiss.

Toggle Mode

Press ⌘⇧/ to open the overlay and keep it pinned. You can then type to search through shortcuts. Press Esc or the same chord again to close.

Shortcut Sources

cmdHalo detects shortcuts from three sources (highest priority first):

Live menu bar — reads the active app's menus in real time via the Accessibility API.
Built-in database — fallback definitions for 15+ popular apps (Finder, Safari, Xcode, VS Code, etc.).
System shortcuts — macOS global shortcuts (screenshots, Spotlight, Mission Control, etc.).

Smart Search (v2.0)

Type in the overlay to search. The search engine combines four signals: exact matches, fuzzy matching (tolerates typos like "cpoy" → "Copy"), intent expansion (typing "duplicate" finds "Copy"), and frequency ranking (your most-used shortcuts appear first).

Context-Aware Ranking (v2.0)

cmdHalo detects what you're doing — editing text, browsing files, writing code, viewing web content — and automatically reorders shortcuts to put the most relevant actions first. Cut/Copy/Paste rise to the top in text fields; Build/Run/Debug dominate in Xcode.

Coach Mode (v2.0)

When enabled, cmdHalo detects when you navigate menus with the mouse instead of using a keyboard shortcut. It shows a gentle notification: "Try ⌘S next time!" — with rate limiting (max 10/day) and a "Don't show again" option per shortcut. Coach mode is opt-in and disabled by default.

Shortcut Sequences (v2.0)

Create multi-step macros triggered by a single shortcut. Example: ⌘⇧N → New Folder → Type today's date → Open folder. Sequences support key presses, text typing, menu actions, delays, and AppleScript. Max 20 steps, 5-second timeout, press Escape to abort.

Workflow Profiles (v2.0)

Profiles like "Dev", "Design", "Writing", and "Browse" auto-activate when associated apps come to front. Each profile boosts relevant shortcut categories (e.g., Dev boosts Build/Run/Debug). Create custom profiles in Settings → Profiles.

Settings & Customization

Open Settings with ⌘, or from the menu bar icon.

Trigger Key

Choose which modifier key triggers the overlay: Command, Option, Control, or Shift.

Hold Delay

How long you need to hold the trigger key before the overlay appears (200-1500 ms).

Overlay Opacity

Adjust the transparency of the shortcut overlay.

Theme

Choose between Light, Dark, or Auto (follows system appearance).

Launch at Login

Automatically start the app when you log into your Mac.

Excluded Apps

Select applications where the overlay should not appear.

Keyboard Shortcuts Reference

cmdHalo's own shortcuts:

Action	Shortcut
Show overlay (hold)	`Hold ⌘ (configurable)`
Toggle overlay (pinned)	`⌘⇧/`
Search shortcuts	`Type while overlay is open`
Close overlay	`Esc or release trigger key`
Open Settings	`⌘,`

Troubleshooting

The overlay does not appear

Make sure Accessibility permission is granted in System Settings → Privacy & Security → Accessibility. If cmdHalo was recently added, try toggling the switch off and back on, or restart the app.

Shortcuts are missing for some apps

cmdHalo reads shortcuts from the app's menu bar. If an app uses non-standard menus (e.g., Electron apps with custom menus), some shortcuts may not be detected. The built-in database provides fallback definitions for popular apps.

License activation fails

Ensure you have an internet connection. Double-check that the license key matches exactly (no extra spaces). If the issue persists, the Gumroad license server may be temporarily unavailable — try again in a few minutes.

macOS says "cmdHalo can't be opened"

Right-click the app → Open, or go to System Settings → Privacy & Security and click "Open Anyway". This happens because the app is downloaded from the internet and is not from the Mac App Store.

The overlay appears but is empty

This can happen with apps that have no keyboard shortcuts in their menu bar. Try switching to a different app (e.g., Finder or Safari) to confirm the overlay works.

FAQ

Is cmdHalo safe? What data does it collect?

cmdHalo runs entirely on your Mac. It reads keyboard shortcuts from app menus using the macOS Accessibility API — it does not log keystrokes, record screen content, or send any data to external servers. License validation is the only network request, and it goes directly to Gumroad's API.

How many devices can I use with one license?

Each license supports up to 2 Mac devices. If you need to deactivate a device, contact support.

Does it work with all apps?

cmdHalo works with any app that exposes keyboard shortcuts in its menu bar (which covers the vast majority of macOS apps). Some apps with fully custom rendering (e.g., certain games or Electron apps) may have limited support.

Can I change the trigger key?

Yes — go to Settings (⌘,) and select your preferred trigger key: Command, Option, Control, or Shift.

Does it work offline?

Yes. After initial activation, cmdHalo works fully offline. The license is revalidated every 30 days when you're online, with a 7-day grace period.

Support

If you have questions, feature requests, or run into issues, reach out at [email protected]. We typically respond within 24 hours.