Slate Deployment and Usage Guide

Prerequisites

• Operating System: macOS 10.6 (Snow Leopard) or later
• Accessibility Permissions: System Preferences > Universal Access > "Enable access for assistive devices" must be checked
• Build Tools (for source compilation): Xcode with Command Line Tools installed

Installation

Method 1: Direct Download

1. Download the latest release:

   • Slate.dmg (GUI installer)
   • slate-latest.tar.gz (Archive)

2. Drag Slate.app to your /Applications folder

Method 2: Terminal Installation

cd /Applications && curl http://www.ninjamonkeysoftware.com/slate/versions/slate-latest.tar.gz | tar -xz

First Launch

1. Open Slate from Applications (or Spotlight)
2. Grant Accessibility permissions when prompted (System Preferences > Security & Privacy > Privacy > Accessibility)
3. Slate will appear in the menu bar with a "S" icon

Configuration

Slate uses a configuration file in your home directory. Create one of the following:

• ~/.slate - Standard configuration syntax
• ~/.slate.js - JavaScript-based configuration (recommended for complex setups)

Basic Configuration Structure

# ~/.slate

# Global settings
config defaultToCurrentScreen true
config windowHintsWidth 100
config windowHintsHeight 100

# Aliases for reusable values
alias full move screenOriginX;screenOriginY screenSizeX;screenSizeY
alias left-half move screenOriginX;screenOriginY screenSizeX/2;screenSizeY

# Key bindings
bind right:ctrl;alt ${full}
bind left:ctrl;alt ${left-half}

# Layouts
layout myLayout 'iTerm' ${full}
layout myLayout 'Safari' ${left-half}

# Default layouts for monitor configurations
default 2:2 myLayout

Available Configuration Directives

Expression Variables

Use these variables in operations:

• screenOriginX, screenOriginY - Screen coordinates
• screenSizeX, screenSizeY - Screen dimensions
• windowTopLeftX, windowTopLeftY - Window position
• windowSizeX, windowSizeY - Window dimensions

JavaScript Configuration

For advanced configurations, use .slate.js:

// ~/.slate.js
Slate.configAll({
  "defaultToCurrentScreen": true,
  "windowHintsWidth": 100
});

var full = Slate.operation("move", {
  "x": "screenOriginX",
  "y": "screenOriginY",
  "width": "screenSizeX",
  "height": "screenSizeY"
});

Slate.bind("right:ctrl;alt", full);

Build & Run

Running Pre-built Binary

# From Applications
open /Applications/Slate.app

# Or from terminal
/Applications/Slate.app/Contents/MacOS/Slate

Building from Source

# Clone repository
git clone https://github.com/jigish/slate.git
cd slate

# Open in Xcode
open Slate.xcodeproj

# Build using xcodebuild (Release)
xcodebuild -project Slate.xcodeproj -scheme Slate -configuration Release build

# Run built binary
open build/Release/Slate.app

Development Mode

For debugging configuration changes without restarting:

1. Enable "Load Config" menu option in Slate preferences
2. Edit ~/.slate file
3. Select "Load Config" from Slate menu bar icon
4. Check Console.app for parsing errors

Deployment

Auto-start Configuration

Add Slate to Login Items:

# Using osascript
osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/Slate.app", hidden:false}'

# Or manually: System Preferences > Users & Groups > Login Items

Configuration Distribution

For team/enterprise deployment:

1. Host configuration file on internal web server or Git repository
2. Deploy via script:

   #!/bin/bash
   curl -o ~/.slate https://internal-server.com/slate-config
   

3. Package with MDM: Include Slate.app and .slate file in deployment package

Backup and Migration

# Backup configuration
cp ~/.slate ~/.slate.backup
cp ~/.slate.js ~/.slate.js.backup

# Export current snapshots (if using snapshot feature)
# Snapshots are stored in ~/Library/Application Support/Slate/snapshots

Troubleshooting

Accessibility Permissions Issues

Problem: Slate shows "Accessibility access is required" warning Solution:

1. System Preferences > Security & Privacy > Privacy > Accessibility
2. Click lock to make changes
3. Check "Slate" in the list (or add it via + button)
4. Restart Slate

Configuration Not Loading

Problem: Changes to .slate file not taking effect Solution:

• Verify file location: ls -la ~/.slate
• Check for syntax errors: Look in Console.app for "Slate" messages
• Reload config: Use "Load Config" menu item or restart Slate
• Test with default config: Remove .slate file temporarily to test with built-in defaults

Key Bindings Not Working

Problem: Keyboard shortcuts not responding Solution:

• Check for conflicts: System Preferences > Keyboard > Shortcuts
• Verify syntax in bind directive: bind key:modifiers operation
• Test with simple binding: bind a:ctrl move screenOriginX;screenOriginY screenSizeX;screenSizeY
• Check if Slate has focus permission: Ensure "Slate" is not in the excluded apps list

Window Operations Failing

Problem: Windows not moving/resizing correctly Solution:

• Check window permissions: Some apps (e.g., System Preferences) cannot be managed
• Verify screen coordinates: Use screenOriginX, screenSizeX variables correctly
• Test with current screen: Set config defaultToCurrentScreen true
• Check multi-monitor setup: Verify screen detection with bind r:ctrl relaunch

Application Switcher Issues

Problem: Window hints not appearing or incorrect Solution:

• Configure hint appearance:

  config windowHintsWidth 100
  config windowHintsHeight 100
  config windowHintsFontSize 50
  

• Ensure window hints are bound: bind e:ctrl window-hints
• Check for overlapping windows: Hints may be obscured by full-screen apps

Performance Issues

Problem: Slate consuming high CPU or lagging Solution:

• Disable window hints if not used (reduces polling)
• Reduce snapshot frequency if using auto-snapshot features
• Check for recursive bindings in config
• Update to latest version: curl command in Installation section

Getting Help

• Logs: Check Console.app for Slate-related messages
• Config Validation: Use source directive to test partial configs
• Community: GitHub Issues at https://github.com/jigish/slate/issues
• Documentation: Wiki at https://github.com/jigish/slate/wiki