Troubleshooting

Solutions to common issues, organized by category.

---

Installation & Permissions

CommandIt doesn’t appear in the menu bar

• Make sure CommandIt is running. Check Activity Monitor for “CommandIt.”
• CommandIt is a menu-bar-only app — it has no Dock icon. Look for the icon in the right side of the menu bar.
• If you have many menu bar items, the icon may be hidden. Try closing other menu bar apps or using a tool like Bartender to reveal it.

Accessibility permission isn’t being recognized

1. Open System Settings > Privacy & Security > Accessibility
2. If CommandIt is listed but unchecked, check the box
3. If CommandIt is listed and checked but still not working, remove it from the list, then re-add it
4. Restart CommandIt after making changes

The remove-and-re-add fix
macOS sometimes caches stale permission state. Removing CommandIt from the Accessibility list and adding it again forces macOS to refresh the permission.

Automation (System Events) permission not granted

1. Open System Settings > Privacy & Security > Automation
2. Find CommandIt in the list
3. Enable System Events under CommandIt
4. If CommandIt doesn’t appear, open CommandIt and try to paste a snippet — macOS shows a permission prompt on the first paste attempt

How do I reset all permissions?

1. Open Terminal
2. Run: tccutil reset Accessibility ai.commandit.CommandIt
3. Run: tccutil reset AppleEvents ai.commandit.CommandIt
4. Restart CommandIt — it will prompt for permissions again on next use

---

Palette & Search

The palette doesn’t appear when I press the hotkey

• Check that CommandIt is running (look for the menu bar icon)
• Another app may be using the same hotkey. Go to Settings > Keyboard Shortcuts and set a different hotkey
• On macOS Sequoia, check System Settings > Keyboard > Keyboard Shortcuts > App Shortcuts for conflicts
• Try the default hotkey: Control+Space

Search results don’t match what I expect

• CommandIt searches snippet names, templates, summaries, categories, and tags
• For exact phrases, type the full phrase — partial word matching uses fuzzy search
• Use filters to narrow results: @Category for category, #tag for tag
• Check that the snippet isn’t in Recently Deleted — deleted snippets don’t appear in normal search

Search is slow

• CommandIt uses SQLite with FTS5 for fast full-text search. Searches should complete in under 50ms.
• If search feels slow, check that you don’t have an extremely large number of snippets (10,000+)
• Restart CommandIt to rebuild the search index

The palette appears on the wrong screen

The palette always opens on the screen where your mouse cursor is. Move your cursor to the desired screen before pressing the hotkey.

---

Auto-Paste

Snippets copy to clipboard but don’t auto-paste

This means the Automation (System Events) permission is missing:

1. Open System Settings > Privacy & Security > Automation
2. Enable System Events under CommandIt
3. If you don’t see CommandIt listed, try pasting a snippet — macOS prompts for permission on the first attempt

Auto-paste doesn’t work in a specific app

Some apps block simulated keystrokes or have custom paste handling:

• Terminal.app — works, but the snippet is pasted as text (not executed)
• Secure input fields (1Password, banking apps) — macOS blocks simulated keystrokes in secure fields for security. Copy to clipboard works; paste manually with Command+V
• Remote desktop apps — the paste keystroke targets the local window, not the remote session. Use clipboard sync between local and remote instead

Auto-paste produces garbled text or wrong content

• Check that no other clipboard manager is interfering (they may modify clipboard contents between copy and paste)
• Increase the paste delay in Settings > General if the target app is slow to accept keystrokes
• Try disabling other clipboard utilities temporarily to isolate the issue

---

Snippets & Templates

Arguments aren’t detected in my snippet

• Arguments use {name} syntax with curly braces: docker run -p {port} {image}
• Argument names must be alphanumeric with underscores: {my_arg} works, {my-arg} does not
• Dynamic variables use double braces: {{date}}, {{clipboard}}, {{shell:...}}
• Make sure there’s no space inside the braces: {port} works, { port } does not

Dynamic variables aren’t being replaced

• Check the syntax: dynamic variables use double curly braces ({{date}}), not single
• Supported variables: {{date}}, {{time}}, {{datetime}}, {{clipboard}}, {{env:NAME}}, {{shell:command}}
• {{shell:...}} requires CommandIt Plus and shows a confirmation dialog before running

Environment variable shows blank value

If {{env:NAME}} resolves to empty when you expected a value:

• The variable may have been denied — check Settings > Security for a “Denied” badge and delete the entry to be prompted again
• The variable may not be set in your shell environment — run echo $NAME in Terminal to verify
• If you chose Not Now, the variable resolves to empty for that paste only — try pasting again and choose Allow

A snippet has too many arguments

If a snippet has many arguments, consider:

• Setting defaults for arguments you rarely change
• Using boolean type for optional flags (they’re excluded entirely when unchecked)
• Splitting into multiple snippets and using the composition queue to combine them

How do I create a snippet with literal curly braces?

To include literal { or } in your snippet text without them being treated as arguments, escape them by doubling: {{ produces { and }} produces }.

This means {{date}} is a dynamic variable, not escaped braces around "date."

---

iCloud Sync

Snippets aren’t syncing between Macs

1. Ensure iCloud Sync is enabled on both Macs: Settings > iCloud Sync
2. Both Macs must be signed in to the same iCloud account
3. Check that iCloud Drive is enabled in System Settings > [Your Name] > iCloud > iCloud Drive
4. Try pressing Sync Now in Settings to force a sync
5. Check your internet connection — iCloud sync requires an active connection

I see duplicate snippets after enabling sync

When you first enable iCloud Sync on a second Mac that already has local snippets, CommandIt merges both sets. If the same snippet exists locally and in iCloud, you may see duplicates. Delete the duplicate from either device and the change syncs.

Sync shows an error or “last synced” time is old

• Check your internet connection
• Verify iCloud is working: open System Settings > [Your Name] > iCloud and check for any account issues
• Try toggling iCloud Sync off and on in Settings > iCloud Sync
• As a last resort, see Reset iCloud Sync data below

iCloud Sync requires CommandIt Plus.

---

AI Features

AI command generation returns an error

• On-device (MLX): Check that the model is downloaded in Settings > AI. The download requires several GB of disk space and Apple Silicon.
• Cloud (BYOK): Verify your API key is correct in Settings > AI. Use the Test Connection button to check.
• Cloud (BYOK): Check that you have API credits remaining with your provider (Claude, OpenAI, or custom).

The AI model download is stuck

• The on-device model is several GB. On slow connections, downloads can take a while.
• Check your internet connection and disk space
• Cancel and restart the download from Settings > AI
• The model requires Apple Silicon (M1 or later). It won’t download on Intel Macs.

AI features aren’t available

• AI Arg Detection and AI Description Generation are free and work without any model download
• AI Command Generation (Command+G) requires CommandIt Plus, plus either the on-device MLX model or a cloud API key
• Command Explanation and Semantic Search also require CommandIt Plus
• Check Settings > AI for the current status of each provider

Semantic search doesn’t find relevant results

Semantic search uses Apple’s NLEmbedding to find snippets by meaning. It works best with:

• Descriptive snippet names and summaries
• Natural language queries (“restart the web server” instead of “nginx”)
• English text (NLEmbedding has the strongest support for English)

---

Performance

CommandIt uses too much memory

• Normal memory usage is 50-150 MB depending on your snippet count
• If you have the on-device AI model loaded, memory usage increases by the model size
• Restart CommandIt to free cached resources

The palette feels sluggish

• Search should respond in under 50ms. If it’s slow, restart CommandIt.
• Check Activity Monitor for CPU-intensive apps that may be starving CommandIt
• Large snippet libraries (10,000+) may benefit from using categories and tags to narrow searches

High CPU usage

• AI operations (command generation, model loading) are CPU-intensive but temporary
• If CPU stays high after AI operations complete, restart CommandIt
• Check that the on-device model isn’t stuck in a generation loop — close the palette to cancel

---

Data & Backup

Where is my data stored?

All snippet data is stored locally in a SQLite database:

~/Library/Application Support/CommandIt/commandit.sqlite

CommandIt creates automatic backups on each launch. Backups are stored alongside the database.

How do I back up my snippets manually?

Two options:

1. JSON Export: In the Library, use File > Export to save your snippets as a JSON file. This is portable and can be imported on any Mac.
2. Database copy: Copy the SQLite file from the path above.

How do I restore from a backup?

Go to Settings > Data and use the Restore from Backup option. Select a backup file to restore.

Restoring replaces all current snippets
A restore operation replaces your entire snippet library with the backup contents. Export your current snippets first if you want to keep them.

How do I export and import snippets?

• Export: In the Library, select the snippets you want (or select all with Command+A), then File > Export
• Import: In the Library, use File > Import and select a JSON file
• Import validates the file and shows a confirmation dialog listing any snippets with shell commands or environment variables

---

Reset Procedures

Reset preferences

Delete the app’s preferences to return all settings to defaults:

defaults delete ai.commandit.CommandIt

Restart CommandIt after running this command.

Reset the database

This deletes all snippets
Resetting the database permanently removes all your snippets, categories, and tags. Export your data first.

1. Quit CommandIt
2. Delete the database file:

rm ~/Library/Application\ Support/CommandIt/commandit.sqlite

3. Restart CommandIt — it creates a fresh database on launch

Reset iCloud Sync data

If sync is in a bad state:

1. Disable iCloud Sync in Settings > iCloud Sync
2. Delete the local database (see above)
3. Restart CommandIt
4. Re-enable iCloud Sync — it pulls fresh data from iCloud

Fresh start (full reset)

To completely reset CommandIt to a clean state:

1. Quit CommandIt
2. Run these commands in Terminal:

defaults delete ai.commandit.CommandIt
rm -rf ~/Library/Application\ Support/CommandIt/

3. Optionally, re-grant permissions (see Reset all permissions)
4. Restart CommandIt — you’ll see the onboarding wizard again

Removing CommandIt entirely?
The steps above reset local data but don't remove the CLI, Keychain items, or MCP integrations. For a full uninstall, see Uninstall.