Neru Deployment & Usage Guide

1. Prerequisites

System Requirements:

macOS 10.15 (Catalina) or later
Go 1.21+ (for building from source)
Homebrew (recommended for installation)
Xcode Command Line Tools (for development builds)

Required Permissions: Neru requires Accessibility permissions to control mouse movements and clicks. You'll need to grant these permissions after installation.

Development Tools (Optional):

just command runner (for building from source)
Git (for cloning the repository)
Nix package manager (for Nix-based installations)

2. Installation

Homebrew Installation (Recommended)

# Add the custom tap
brew tap y3owk1n/tap

# Install Neru
brew install --cask y3owk1n/tap/neru

Nix Installation

# Add to your flake.nix inputs:
inputs.neru.url = "github:y3owk1n/neru";

# For nix-darwin/home-manager setup, see docs/INSTALLATION.md

Build from Source

# Clone the repository
git clone https://github.com/y3owk1n/neru.git
cd neru

# Build the release version
just release

# The binary will be available at ./dist/neru

Manual Download

Download the latest release from the GitHub Releases page.

3. Configuration

Grant Permissions

After installation:

Open System Settings → Privacy & Security → Accessibility
Click the lock icon (bottom left) to make changes
Enable Neru in the list of applications
Restart Neru if it's already running

Configuration Files

Neru uses TOML configuration files. The default location is:

~/.config/neru/config.toml (user-specific)
/etc/neru/config.toml (system-wide)

Basic Configuration Example

Create ~/.config/neru/config.toml:

[hotkeys]
"Cmd+Shift+Space" = "hints"
"Cmd+Shift+G" = "grid"
"Cmd+Shift+C" = "recursive-grid"
"Cmd+Shift+S" = "scroll"

[hints]
enabled = true
hint_characters = "asdfghjkl"
background_color = "#FFD700"
text_color = "#000000"
font_size = 14
clickable_roles = [
  "AXButton",
  "AXLink",
  "AXMenuItem",
  "AXRadioButton",
  "AXCheckBox",
  "AXTextField",
  "AXTextArea",
  "AXStaticText",
  "AXList",
  "AXOutline",
  "AXTable",
  "AXCell",
  "AXMenuBarItem",
  "AXDockItem"
]

[grid]
lines_count = 4
background_color = "#00000080"
border_color = "#FFD700"
border_width = 2

[scroll]
enabled = true
scroll_up = "k"
scroll_down = "j"
scroll_up_fast = "K"
scroll_down_fast = "J"
scroll_to_top = "gg"
scroll_to_bottom = "G"

[exclude]
apps = ["com.apple.Terminal", "com.googlecode.iterm2"]

Configuration Validation

Neru validates configuration with the following rules:

hint_characters must contain at least 2 ASCII characters
Colors must be valid hex codes
Font sizes must be between 6 and 72
Hotkey combinations must use valid modifiers (Cmd, Ctrl, Alt, Shift, Option)

Environment Variables

# Enable debug logging
export NERU_DEBUG=1

# Specify custom config location
export NERU_CONFIG_PATH=/path/to/config.toml

# Set log level (debug, info, warn, error)
export NERU_LOG_LEVEL=debug

4. Build & Run

Development Build

# Clone and setup
git clone https://github.com/y3owk1n/neru.git
cd neru

# Install dependencies
go mod download

# Build development version
go build -o neru ./cmd/neru

# Run locally
./neru

Production Build

# Build optimized release
just release

# Or manually
go build -ldflags="-s -w" -o neru ./cmd/neru

# Install to /usr/local/bin
sudo cp neru /usr/local/bin/

Running as a Service

# Install as a launchd service (auto-start on login)
neru services install

# Start the service
neru services start

# Check service status
neru services status

# Stop the service
neru services stop

# Uninstall service
neru services uninstall

Manual Run

# Start Neru application
open -a Neru

# Or from command line
neru

5. Deployment

Distribution Methods

Homebrew Cask (Recommended for Users):

# Update your tap repository with new releases
# The tap is maintained at: https://github.com/y3owk1n/homebrew-tap

Nix Package:

# Add to your Nix configuration
neru = pkgs.callPackage ./neru.nix {};

# Or use the flake
inputs.neru = {
  url = "github:y3owk1n/neru";
  inputs.nixpkgs.follows = "nixpkgs";
};

Standalone DMG:

Build the release with just release
Package using create-dmg or similar tools
Sign with Apple Developer ID for distribution
Upload to GitHub Releases

App Store Distribution (Future):

Requires Apple Developer Program membership ($99/year)
Needs sandboxing and App Store compliance
Not currently implemented but possible

Code Signing & Notarization

For production distribution on macOS:

# Sign the binary
codesign --force --sign "Developer ID Application: Your Name" neru

# Notarize (requires Apple Developer account)
xcrun notarytool submit neru.zip --apple-id "your@email.com" --team-id "TEAMID" --wait

Update Mechanism

Neru currently uses manual updates via:

Homebrew: brew upgrade neru
Nix: nix flake update
Manual download from GitHub Releases

6. Troubleshooting

Common Issues

1. Neru doesn't respond to hotkeys

# Check if Neru is running
ps aux | grep neru

# Check Accessibility permissions
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

# Try restarting Neru
pkill neru && open -a Neru

2. Grid or hints don't appear

# Check logs
tail -f ~/Library/Logs/neru.log

# Verify config file exists
ls -la ~/.config/neru/config.toml

# Reset to default config
rm ~/.config/neru/config.toml && neru

3. Performance issues

# In config.toml, reduce grid complexity
[grid]
lines_count = 3  # Reduce from default 4

# Exclude problematic apps
[exclude]
apps = ["com.parallels.desktop", "com.vmware.fusion"]

4. Build errors

# Ensure Go version is compatible
go version  # Should be 1.21+

# Clean build cache
go clean -cache

# Update dependencies
go mod tidy

5. Permission errors after update

# Remove and re-add Neru in Accessibility settings
# Sometimes macOS resets permissions after updates

# Also check Screen Recording permissions if grid mode has issues
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenRecording"

Debug Mode

# Run with verbose logging
NERU_LOG_LEVEL=debug neru

# Check system logs
log stream --predicate 'subsystem contains "neru"'

# Generate debug report
neru debug-report > neru-debug.txt

Known Limitations

Requires macOS 10.15+
Some Electron apps may have accessibility limitations
Multiple monitor setups may have coordinate issues
Screen sharing apps might interfere with overlay rendering

Getting Help

Check the GitHub Issues
Review the documentation in the repository
Enable debug logging and share logs when reporting issues
Verify your configuration with neru validate-config

How to Deploy & Use neru