Troubleshooting

Quick fixes for common issues. Jump to your symptom:

• The app shows a security warning on open
• Pairing won’t complete
• My device shows “Offline”
• The action buttons are greyed out
• I clicked an action but nothing happened
• A delayed lock never fired
• I’m not getting notification banners
• commandlatch: command not found
• Lock fires immediately instead of waiting
• A shortcut or webhook is rejected
• Export diagnostics for a bug report

The single most common cause of “nothing happens” is that the Mac is asleep, closed, offline, or the app isn’t running — CommandLatch can only act on a Mac that’s awake and online. Check the device status first.

The app shows a security warning on open

If macOS displays a security warning when opening CommandLatch, re-download directly from https://commandlatch.app/#download — official releases are signed and notarized and should open without any warnings. If the issue continues after re-downloading, contact us at support@commandlatch.app.

Pairing won’t complete

• “Code expired” or it’s rejected. Pairing codes last ~10 minutes. Get a fresh one from the menu-bar icon (top item: Pairing code: …) and re-enter it.
• The sign-in email never arrived. Check spam, confirm the address, wait a minute, request it again.
• Typed the code but the device never appears. Make sure the Mac is online and the menu-bar app is running, then try a fresh code.

Full flow: Pair your Mac.

My device shows “Offline”

A device is Online only while the Mac is awake, connected, and running CommandLatch. It shows Offline when any of those isn’t true. Check, in order:

1. Is the app running? Look for the menu-bar icon. If it’s gone, reopen CommandLatch from Applications.
2. Is the Mac awake and online? A sleeping or closed-lid Mac can’t send heartbeats. CommandLatch cannot wake a sleeping Mac — that’s a known limitation.
3. Did it just reconnect? After waking, give it a few seconds to flip back to Online.

Keep the app running automatically with Settings → Startup → Start CommandLatch on login.

The action buttons are greyed out

In the dashboard, buttons are disabled when:

• the device is Offline (see above), or
• another command for that device is still in flight (wait a moment), or
• the device has Remote commands disabled — re-enable it on the Mac (menu bar → Enable Remote Commands; the dashboard shows the state but can’t change it).

I clicked an action but nothing happened

1. Confirm the device is Online.
2. Confirm Remote commands are enabled for it.
3. Remember actions are queued — they run on the Mac’s next poll, usually within a couple of seconds. Sleep and Lock + Sleep can keep showing queued until the Mac wakes; that’s expected, the Mac reports the result only after waking.
4. From a terminal, commandlatch status confirms which device you’re driving and that it’s reachable.

A delayed lock never fired

For a scheduled (--lock-sleep-after, “In 5 minutes”, or Claude Code hook) lock:

• Make sure you didn’t already cancel it (the menu’s Cancel Pending Action item, the dashboard’s Cancel button, or commandlatch done --cancel).
• The Mac must stay online through the countdown. If it went offline, the lock can’t fire.
• Stuck countdown in the dashboard? If the app quit while holding a pending lock, the dashboard may keep showing the countdown. Click Cancel there — the next time the app comes online it clears the stale pending state.

I’m not getting notification banners

Banners — the send_notification action, including the “Locking in …” warning posted before a delayed lock — go through macOS Notifications, so:

• Allow notifications for CommandLatch. The menu bar’s Settings → Security checks shows the current state with a Turn on notifications button. The app also prompts on first launch — say Allow.
• Do Not Disturb / Focus silences banners. Turn it off, or allow CommandLatch through your Focus settings.

Note that a silenced banner doesn’t stop the action — a delayed lock still fires on time even if you never saw the warning.

commandlatch: command not found

• Install the CLI from the menu bar: Settings → Command-line tool → Install commandlatch on PATH. See Install → command-line tool.
• In a script or automation, the PATH may differ from your interactive shell. Use the full path: /usr/local/bin/commandlatch.

Lock fires immediately instead of waiting

A duration flag with no space — --lock-sleep-after5m — is read as an unknown argument, so the delay is dropped. Use a space or =:

commandlatch done --notify --lock-sleep-after 5m     # correct — note the space
commandlatch done --notify --lock-sleep-after=5m     # the = form also works

Durations are a number with an optional s/m/h (no suffix = seconds).

A shortcut or webhook is rejected

Response	Meaning	Fix
invalid_token	The URL’s last segment is wrong.	Re-copy the exact URL; no trailing slash or query string.
remote_disabled	The device has remote commands off.	Re-enable on the Mac (menu bar).
rate_limited	Too many calls in a minute.	Wait a moment and try again. Contact support if a legitimate automation keeps hitting this.
nothing happens	The command expired before the Mac saw it.	Make sure the device is Online; shortcut commands expire after 60s.

More: Shortcut endpoints, Webhooks.

Export diagnostics for a bug report

When reporting a problem, attach a diagnostics bundle:

• Menu bar → Diagnostics, or Settings → Diagnostics → Export diagnostics.

It writes a commandlatch-diagnostics-<timestamp>.json file and reveals it in Finder. The bundle is redacted — it includes the app version, OS, system checks, and recent events, but not your device token or keys — so it’s safe to share.

You can also open Settings → Diagnostics → Open data folder to browse the raw app files.

Submit a support ticket

Rather than exporting a bundle and emailing it yourself, you can file a ticket from inside the app and we’ll reply by email:

• Dashboard: open Support in the sidebar (or Settings → Support on mobile), pick a category, and describe the issue. Past tickets are listed on the same page.
• Desktop app: Settings → Contact support. Leave Attach diagnostics on (the default) and the redacted bundle described above is sent with your ticket automatically — no separate export step.

You can still email support@commandlatch.app directly if you prefer.

---

Still stuck? The deeper reference docs cover edge cases: CLI · Claude Code hook · Shortcut endpoints · Webhooks · Known limitations.