Spectacle Deployment and Usage Guide

Prerequisites

• macOS: Spectacle requires macOS 10.9 or greater (version 0.8.6 supports 10.7, version 0.7 supports 10.6)
• Developer Tools: Xcode Command Line Tools for building from source
• Accessibility Permissions: OS X Accessibility Protocol access required for Spectacle to function

Installation

Installing the Pre-built Binary

1. Download the latest release from the GitHub Releases page
2. Move the Spectacle.app to your Applications folder
3. Launch Spectacle.app

Building from Source

1. Clone the repository:

   git clone https://github.com/eczarny/spectacle.git
   cd spectacle
   

2. Open the project in Xcode:

   open Spectacle.xcodeproj
   

3. Build and run the project using Xcode's Build and Run buttons

Configuration

Accessibility Permissions

When you first launch Spectacle, macOS will prompt you to grant accessibility permissions:

1. Click "Open System Preferences" in the dialog
2. Enable Spectacle in the Accessibility section
3. Restart Spectacle

Keyboard Shortcuts

Spectacle uses the following modifier keys by default:

• Command Key: ⌘
• Control Key: ⌃
• Option Key: ⌥
• Shift Key: ⇧

You can customize all keyboard shortcuts through Spectacle's preferences:

1. Click the Spectacle icon in the menu bar
2. Select "Preferences"
3. Click on any shortcut to change it
4. Press the new key combination
5. Click "Done"

Build & Run

Development

1. Open Spectacle.xcodeproj in Xcode
2. Select the target scheme (Spectacle)
3. Click the "Run" button or press Cmd+R
4. The app will launch and start running

Production

1. In Xcode, select "Product" → "Archive"
2. In the Archives organizer, select your archive
3. Click "Distribute App"
4. Choose your distribution method (Developer ID-signed, etc.)

Deployment

Spectacle is a macOS application that runs locally. There is no server-side deployment required. For distributing to other users:

1. Developer ID Signing: Sign the app with your Developer ID for distribution outside the Mac App Store
2. Mac App Store: Submit through App Store Connect (if you have distribution rights)
3. Direct Distribution: Share the .app bundle directly with users

Troubleshooting

Common Issues and Solutions

Spectacle is requesting access to use accessibility features

• Issue: Spectacle cannot control windows without accessibility permissions
• Solution: Grant access in System Preferences → Security & Privacy → Privacy → Accessibility

Spectacle does not resize a particular window as expected

• Issue: Some applications set minimum/maximum window size constraints
• Solution: This is expected behavior. Spectacle respects window constraints set by applications

Spectacle behaves strangely with Terminal windows

• Issue: Terminal applications constrain window resizing to maintain complete rows/columns
• Solution: Spectacle will work around these constraints, but resizing may not be pixel-perfect

Keyboard shortcuts not working

• Issue: Shortcuts may conflict with other applications or system shortcuts
• Solution:
  1. Check Spectacle preferences and change conflicting shortcuts
  2. Ensure Spectacle is running (check menu bar)
  3. Verify accessibility permissions are granted

Spectacle not launching at login

• Issue: App doesn't start automatically when you log in
• Solution:
  1. Open System Preferences → Users & Groups
  2. Select your user account
  3. Click "Login Items"
  4. Add Spectacle.app

Performance issues with multiple displays

• Issue: Window positioning may be slower or less accurate with multiple monitors
• Solution: Ensure all displays are properly configured in System Preferences → Displays

Getting Help

Since the project is no longer actively maintained, consider these alternatives:

• Rectangle: A community-maintained fork with similar functionality
• Check the issues: Browse existing GitHub issues for similar problems
• Open an issue: Report bugs or request features (though response may be limited)

Uninstallation

To completely remove Spectacle:

1. Quit the application
2. Move Spectacle.app from Applications to Trash
3. Remove preferences:

   rm -rf ~/Library/Preferences/com.divisiblebyzero.Spectacle.plist
   

4. Remove application support files:

   rm -rf ~/Library/Application\ Support/Spectacle/