macOS permissions

Almost every "my Mac automation broke" is one of five things. Work through them in order.

1. Check state

chewie doctor

Reports each grant, names the exact app that needs it, and lists which tools are on PATH.

2. You cannot grant these from code

Believe this before you spend an hour on it.

• tccutil only resets. There is no tccutil grant.
• The TCC database is SIP-protected. Editing it does not work.
• The only programmatic grant is an MDM PPPC profile, requiring an enrolled machine.

Everything else is a human clicking a toggle. Design around that instead of fighting it.

3. Grant it to the right app

The app hosting the agent, not the agent, and not the CLI. A CLI binary has no bundle identity, so macOS attributes its requests up the responsibility chain to whatever .app launched it.

Consequences that confuse people:

• The prompt says "Cursor wants to control Finder" when it was your script
• It works in Terminal and silently fails in VS Code, because grants are per host
• Two different tools launched by the same terminal share one grant

chewie doctor resolves the outermost .app and prints its name.

4. The buckets are separate

Having one gives you none of the others. Automation is per pair: controlling Mail and controlling Safari are two separate grants.

5. The prompt only appears once, ever

If the user hit Don't Allow, or the prompt appeared while the terminal was in the background and got dismissed, it never comes back. The automation fails silently forever. This is the real cause of most "it worked yesterday."

tccutil reset AppleEvents          # then trigger it again, terminal in the FOREGROUND
tccutil reset Accessibility
tccutil reset All com.example.app

Warn the user before running any reset. You are deleting grants they clicked through by hand and they will have to redo every one.

Error signatures

Walking a human through it

One toggle at a time. Do not list all five.

1. Open System Settings > Privacy & Security > Accessibility
2. Click +, add the app chewie doctor named
3. Make sure the toggle is actually ON, not just listed
4. Quit and reopen that app. The grant does not take effect until relaunch.
5. chewie doctor again

Step 4 is the one everybody skips.

Say the scope out loud

Accessibility plus Screen Recording is functionally total control of the session: read every pixel, click every button, type into anything. Full Disk Access adds every file. That is worth telling the user plainly rather than burying it in an installer.

Two real mitigations: keep grants on a terminal they control rather than a general-purpose app, and put anything long-running or internet-driven in a VM.

Full detail: docs/PERMISSIONS.md.