Troubleshooting
Common issues and how to fix them.
Quick Fixes
Before diving into specific issues, try these general troubleshooting steps:
1. Restart the Agent
Right-click the agent in the sidebar and select "Restart". This clears the terminal and starts fresh.
2. Restart Cliio
Quit Cliio completely (Cmd+Q) and reopen it. Sessions will restore automatically if tmux is installed.
3. Check for Updates
Make sure you're running the latest version. If installed via Homebrew, run: brew upgrade cliio
4. Reset Settings
If settings are corrupted, reset them by deleting the settings file and restarting Cliio.
Common Issues
Startup Issues
CLI Issues
Persistence Issues
Authentication
Network
Display Issues
Performance
UI Issues
Debug Mode
If you're experiencing persistent issues, enable debug mode to see detailed logs that can help diagnose problems.
Enable Debug Logging
Start Cliio from the terminal with debug flags:
# Open Cliio with debug logging
/Applications/Cliio.app/Contents/MacOS/Cliio --enable-logging
# Logs will be written to:
~/Library/Logs/Cliio/main.logView System Logs
Use macOS Console app to view detailed system logs:
- 1.Open Console app (in /Applications/Utilities/)
- 2.Search for "Cliio" in the search bar
- 3.Look for error messages or stack traces
Sharing Logs
Still Need Help?
If your issue isn't listed here or the solutions don't work, we're here to help.
Complete Reinstall
If all else fails, try a clean reinstall. This will remove all settings and agent configurations.
# 1. Quit Cliio
# 2. Uninstall
brew uninstall --cask cliio
# 3. Remove app data
rm -rf ~/Library/Application\ Support/Cliio
rm -rf ~/Library/Preferences/com.cliio.app.plist
rm -rf ~/Library/Logs/Cliio
# 4. Reinstall
brew install --cask cliio