Toggle Display Profile Scripts — User Guide

Version: 1.2
Platform: macOS
Author: Knut Larsson

Toggle Display Profile provides interactive bash scripts for quickly switching between ICC display profiles on macOS using ArgyllCMS dispwin. Two versions are included: one for the primary display and one for the secondary display, along with macOS Automator app files for convenient access.

📑 Table of Contents

Overview

These scripts provide a quick and convenient way to switch between ICC display profiles on macOS. They are designed for users who need to frequently change display profiles for different workflows or display modes.

The scripts are particularly useful for:

The scripts remember your last selected profile and preselect the next one in the list for rapid toggling, making frequent profile changes effortless.

Scripts and Applications

The Toggle Display Profile project provides two bash scripts and two macOS Automator applications.

Bash Scripts

ToggleDisplayProfile_Main.command

ToggleDisplayProfile_Second.command

Both scripts are identical in functionality and features, differing only in the DISPLAY_NUMBER configuration.

Automator Applications

The Automator app files are compressed in file Automator_app_files.zip. Make sure to read the Important note below.

Toggle Display Profile-Main.app

Toggle Display Profile-Second.app

Note: The Automator apps will prompt for the .command script location on first run or if the stored path becomes invalid (e.g., if you move the script). This allows flexibility in script placement.

IMPORTANT: Sometimes the Automator .app files may be interpreted by macOS as faulty when trying to run them. In this case a “damaged” error could appear because macOS applies a com.apple.quarantine attribute to downloaded files, which, when combined with signature changes during compression/extraction, triggers security.

If this happens: Remove Quarantine Attribute After downloading, run this command in Terminal to remove the restriction, replacing /path/to/app with the actual path to your Automator app file:

xattr -dr com.apple.quarantine "/path/to/app/Toggle Display Profile.app"

Features

General Features

Profile Management

User Experience

When to Use These Scripts

Multi-Mode Displays

Many modern monitors have switchable display modes that change the color gamut:

Problem: When you switch the monitor’s hardware mode, the software ICC profile must also change to match. Otherwise, colors will be displayed incorrectly.

Solution: Use these scripts to quickly apply the matching ICC profile whenever you change the monitor mode.

Wide-Gamut Displays on sRGB Content

Displays with wide color gamuts (e.g., 99% AdobeRGB) will show oversaturated colors when displaying sRGB content without proper color management.

Problem: Working on sRGB images on an AdobeRGB display causes colors to appear saturated and inaccurate.

Solution: Use ICC profiles with Perceptual intent that force out-of-gamut colors into the sRGB color space. Set your software (Photoshop, Krita, GIMP) to manage colors with this profile using perceptual intent.

Multiple Luminance Profiles

Different workflows require different screen brightness levels:

Solution: Create and switch between profiles calibrated for different luminance levels.

Dual-Monitor Workflows

When using two displays with different characteristics:

Solution: Use the Main script for the primary display and the Second script for the secondary display, each with its own set of profiles.

Installation

Getting Started

  1. Download or clone the Toggle Display Profile repository
  2. Place the folder in a convenient location (Desktop, Documents, etc.)
  3. Install dependencies (see Dependencies)
  4. Configure profile lists (see Configuring Profile Lists)
  5. Set execute permissions (see Execution Permissions for macOS (Important))
  6. Copy or drag .app files to Dock or to Applications folder (if desired).
    Alternatively, make keyboard shortcut to .app files.
  7. Run the script to verify it works

Dependencies

The scripts require ArgyllCMS to be installed on your system.

Install ArgyllCMS via Homebrew (recommended):

brew install argyll-cms

Verify installation:

dispwin -?

If dispwin is found, ArgyllCMS is properly installed.

Alternative installation:

Download from ArgyllCMS website and follow the installation instructions for macOS.

Script Placement

You may place the Toggle Display Profile folder in any location:

The scripts and Automator apps will work from any location. The Automator apps will ask for the script location on first run and remember it.

Execution Permissions for macOS (Important)

On modern macOS versions, a script must have the execute bit set to run.

After setting permissions, you can run scripts by:

Option 1: Set Execute Bit Using Terminal (recommended)

  1. Open Terminal

  2. Navigate to the Toggle Display Profile folder:

    cd "/path/to/Toggle_Display_Profile"

  3. Set execute permissions for both scripts:

     chmod +x ToggleDisplayProfile_Main.command   
 chmod +x ToggleDisplayProfile_Second.command

  4. Verify (optional):

    ls -l *.command

    Expected output:

    -rwxr-xr-x@ ToggleDisplayProfile_Main.command
-rwxr-xr-x@ ToggleDisplayProfile_Second.command

Option 2: Set Execute Bit Using Finder

  1. Right-click (or Ctrl+click) on the .command file
  2. Select “Open”
  3. Click “Open” in the security dialog
  4. This may work in many cases without using Terminal

Configuring Profile Lists

Before using the scripts, you need to configure them with your ICC profiles.

Edit the script configuration:

  1. Open the .command file in a text editor (TextEdit, VS Code, etc.)
  2. Locate the USER CONFIG section (around line 67)
  3. Modify the following parameters:

Key Parameters:

Important: The DESCRIPTIONS array must have the same number of entries as PROFILES, and the order must match exactly.

Configuration Files:

The scripts and .app files automatically create configuration files at:

$HOME/Library/Application Support/ToggleDisplayProfile/

The file icc_state remembers the last selected profile for each .command script.
The file config remembers the location of the .command script when using the .app files.

Multiple scripts can share these files safely using script-specific tags. Only criteria is that the file names of the .command script and the .app file must be unique for each screen they are used for.

Usage

Using the .command Scripts Directly

Method 1: Double-click in Finder

  1. Navigate to the Toggle Display Profile folder in Finder
  2. Double-click ToggleDisplayProfile_Main.command or ToggleDisplayProfile_Second.command
  3. A Terminal window will open
  4. An AppleScript dialog will appear with your profile list
  5. Select a profile and click “OK”
  6. The profile will be applied to the target display
  7. A success message will show the applied profile and description

Method 2: Run from Terminal

  1. Open Terminal

  2. Navigate to the script folder:

    cd "/path/to/Toggle_Display_Profile"

  3. Run the script:

    ./ToggleDisplayProfile_Main.command

    or

    ./ToggleDisplayProfile_Second.command

Dialog Behavior:

Using the Automator Apps

First Run:

  1. Double-click Toggle Display Profile-Main.app or Toggle Display Profile-Second.app (or click once if icon is in the Dock).
  2. The app will ask for the location of the corresponding .command script.
  3. Navigate to the Toggle Display Profile folder.
  4. Select the appropriate .command file:
    • Main app → ToggleDisplayProfile_Main.command.
    • Second app → ToggleDisplayProfile_Second.command.
  5. The app will store this path and run the script

Subsequent Runs:

  1. Double-click the app (or click once if icon is in the Dock).
  2. It will automatically run the stored script.
  3. The profile selection dialog will appear.
  4. Select and apply a profile as usual.

If Script Path Changes:

If you move the .command script to a new location, or delete the “State file” (see earlier chapter) the app will ask for the new path on the next run.

Adding to macOS Dock

For quick access, you can add the Automator apps to your macOS Dock:

Using macOS Menu Bar (macOS Ventura and later):

  1. Open System Settings → Desktop & Dock
  2. Enable “Automatically hide and show the Dock” (optional)
  3. Create an alias of the app:
    • Right-click the app → “Make Alias”
  4. Drag the alias to your Desktop or a convenient location
  5. Drag the alias to the right side of the Dock
  6. The app will appear in the Dock for quick access

Alternative: Add to Dock

  1. Drag the .app file to the Dock
  2. Right-click the Dock icon → Options → “Keep in Dock”
  3. Click the Dock icon to quickly run the app

Alternative: Keyboard Shortcut

You can create a keyboard shortcut using Automator or third-party tools:

  1. Open Automator
  2. Create a new “Quick Action” or “Application”
  3. Add “Run Shell Script” action
  4. Enter: open "/path/to/Toggle Display Profile-Main.app"
  5. Save as “Toggle Main Profile” or similar
  6. In System Settings → Keyboard → Keyboard Shortcuts, assign a shortcut

Example Scenarios

Scenario 1: Switching Monitor Modes

Setup:

Workflow:

  1. For web design (sRGB):
    • Switch monitor to sRGB mode via monitor controls
    • Run Toggle Display Profile-Main.app
    • Select the sRGB profile
    • Work on web content with accurate colors
  2. For photography (AdobeRGB):
    • Switch monitor to AdobeRGB mode via monitor controls
    • Run Toggle Display Profile-Main.app
    • Select the AdobeRGB profile
    • Edit photos with wider color gamut

Result: Colors are displayed accurately for each workflow mode.

Scenario 2: Wide-Gamut Display for sRGB Work

Setup:

Workflow:

  1. Open Photoshop
  2. Set color management to use the ICC profile made with Perceptual intent for sRGB (typically done with ArgyllCMS).
  3. Run Toggle Display Profile-Main.app
  4. Select the ICC profile with sRGB Perceptual intent.
  5. Work on sRGB images
  6. Colors appear correctly (not oversaturated)

Result: sRGB images display accurately on the wide-gamut display.

Scenario 3: Day/Night Luminance Switching

Setup:

Workflow:

  1. Daytime work:
    • Run Toggle Display Profile-Main.app
    • Select the 120 cd/m² profile
    • Work comfortably in bright environment
  2. Nighttime work:
    • Run Toggle Display Profile-Main.app
    • Select the 80 cd/m² profile
    • Work comfortably in dim environment

Result: Appropriate brightness for ambient lighting conditions.

Scenario 4: Dual-Monitor Setup

Setup:

Workflow:

  1. Configure primary display:
    • Use ToggleDisplayProfile_Main.command with wide-gamut profiles
    • Create app: Toggle Display Profile-Main.app
  2. Configure secondary display:
    • Use ToggleDisplayProfile_Second.command with standard profiles
    • Create app: Toggle Display Profile-Second.app
  3. Switch profiles independently:
    • Run Main app to change primary display profile
    • Run Second app to change secondary display profile

Result: Each display has appropriate profiles for its purpose.

Files and Folder Structure

Toggle_Display_Profile/
├── ToggleDisplayProfile_Main.command           # Bash script for primary display
├── ToggleDisplayProfile_Second.command         # Bash script for secondary display
├── Toggle Display Profile-Main.app/            # Automator app for primary display
├── Toggle Display Profile-Second.app/          # Automator app for secondary display
├── README.md                                   # Basic project description
├── index.md                                    # This user guide
configuration

User Data (created automatically):
└── ~/Library/Application Support/ToggleDisplayProfile/
    └── icc_state                               # Persistent state file
    └── config                                  # Persistent command path

State File Format:

The icc_state file stores the last selected profile index for each script:

ToggleDisplayProfile_Main.command=1
ToggleDisplayProfile_Second.command=0

Each line uses the script filename as a tag, allowing multiple scripts to share the same state file.

Similar logic is used for config file tags.

Configuration Parameters

DISPLAY_NUMBER

PROFILE_DIR

PROFILES

DESCRIPTIONS

How It Works

Script Execution Flow

  1. Initialization
    • Check for ArgyllCMS (dispwin) availability
    • Validate PROFILES and DESCRIPTIONS arrays match
    • Verify profile directory exists
    • Create state file directory if needed
  2. State Detection
    • Read current profile index from state file using script tag
    • If no state exists or is invalid, default to index 0 (first profile)
  3. Dialog Preparation
    • Build profile list with current profile marked “(current)”
    • Calculate next profile index (wraps around to beginning)
    • Preselect next profile for convenient toggling
  4. User Interaction
    • Show AppleScript dialog with profile list
    • Wait for user selection or cancellation
    • If cancelled, display message and close Terminal
  5. Profile Application
    • Validate selected profile file exists and is readable
    • Verify profile has valid ICC/ICM extension
    • Validate DISPLAY_NUMBER is numeric
    • Run dispwin -d <DISPLAY_NUMBER> -I <PROFILE_PATH> to apply profile
    • Check for warnings in dispwin output
  6. State Persistence
    • Update state file with new profile index
    • Use script-specific tag to avoid conflicts
    • Handle shared state file with multiple scripts
  7. Success Feedback
    • Display success message in Terminal
    • Show macOS popup dialog with profile name and description
    • Exit cleanly

ArgyllCMS dispwin Command

The scripts use the following ArgyllCMS dispwin command:

dispwin -d <DISPLAY_NUMBER> -I <PROFILE_PATH>

Parameters:

Output Handling:

State File Management

The state file uses a simple tag-based format:

<script_tag>=<profile_index>

Example:

ToggleDisplayProfile_Main.command=2
ToggleDisplayProfile_Second.command=0

Update Process:

  1. Read entire state file
  2. Remove existing entry for current script tag
  3. Append new entry with updated index
  4. Write back to file

This allows multiple scripts to safely share one state file.

Important Notes and Best Practices

Profile Calibration

Color Management in Applications

Script Configuration

Workflow Tips

Performance and Reliability

Troubleshooting

Script won’t run

Problem: Double-clicking the .command file doesn’t open it.

Solutions:

  1. Check execute permissions:

    ls -l ToggleDisplayProfile_Main.command

    Look for -rwxr-xr-x (execute bit set). If not set:

    chmod +x ToggleDisplayProfile_Main.command

  2. Try Ctrl+right-click → Open:

    • Right-click (or Ctrl+click) the file
    • Select “Open”
    • Click “Open” in the security dialog

  3. Run from Terminal:

    ./ToggleDisplayProfile_Main.command

Script does not find ArgyllCMS

Problem: Error message “ArgyllCMS (dispwin) not found”

Solutions:

  1. Verify ArgyllCMS is installed:

    brew list argyll-cms

  2. Install ArgyllCMS:

    brew install argyll-cms

  3. Verify dispwin is available:

    dispwin -?

  4. Check PATH variable:

    echo $PATH | grep argyll

Profile file not found

Problem: Error message “Profile file not found”

Solutions:

  1. Verify profile directory:
    • Check PROFILE_DIR in the script
    • Ensure the directory exists: ls "$HOME/Library/ColorSync/Profiles"
  2. Verify profile filename:
    • Check PROFILES array in the script
    • Ensure filenames match exactly (case-sensitive)
    • Verify files exist: ls "$HOME/Library/ColorSync/Profiles/*.icc"
  3. Check for typos:
    • Profile filenames in PROFILES array must match actual filenames
    • No extra spaces or quotes

Profile not applied correctly

Problem: Profile appears to apply but colors don’t change

Solutions:

  1. Verify display number:
    • Run dispwin -d to list displays
    • Ensure DISPLAY_NUMBER matches the target display
  2. Check monitor hardware mode:
    • If monitor has switchable modes, ensure hardware mode matches profile
    • Example: sRGB profile requires sRGB hardware mode
  3. Restart applications:
    • Some applications need to be restarted to recognize new profiles
    • macOS may need a moment to update color management
  4. Verify profile is valid:
    • Open profile in ColorSync Utility to verify it’s valid
    • Check profile description and intended use

Dialog doesn’t appear

Problem: Terminal opens but no profile selection dialog appears

Solutions:

  1. Check AppleScript permissions:
    • System Settings → Privacy & Security → Automation
    • Ensure Terminal has permission to control System Events
  2. Check for Terminal focus issues:
    • The script attempts to bring Terminal to front
    • Check if dialog is hidden behind other open windows

  3. Run from Terminal directly:

    ./ToggleDisplayProfile_Main.command

    Watch for error messages in Terminal output

Automator app asks for script location repeatedly

Problem: The .app asks for the script location every time it’s run

Solutions:

  1. Check configuration path:
    • The app stores the script path in config file.
    • If the script moved, the app will ask for the new location.
    • The app must have write permission to configuration path to remember path.
  2. Keep script in consistent location:
    • Place scripts in a permanent location
    • Avoid moving scripts after initial configuration
  3. Reconfigure app:
    • When prompted, select the correct .command file
    • The app will remember the new path

State file issues

Problem: Script doesn’t remember last selected profile

Solutions:

  1. Check state file location:

    ls -la "$HOME/Library/Application Support/ToggleDisplayProfile/"

  2. Verify state file contents:

    cat "$HOME/Library/Application Support/ToggleDisplayProfile/icc_state"

  3. Check permissions:

    ls -l "$HOME/Library/Application Support/ToggleDisplayProfile/icc_state"

    Should be readable and writable

  4. Delete state file to reset:

    rm "$HOME/Library/Application Support/ToggleDisplayProfile/icc_state"

    Script will recreate it on next run

Multiple displays not working correctly

Problem: Both scripts seem to affect the same display

Solutions:

  1. Verify display numbering:

    dispwin -d

    This lists all displays with their ArgyllCMS numbers

  2. Check DISPLAY_NUMBER settings:
    • Main script should have DISPLAY_NUMBER="1"
    • Second script should have DISPLAY_NUMBER="2"
  3. Test each script independently:
    • Run Main script, observe which display changes
    • Run Second script, observe which display changes
    • Adjust DISPLAY_NUMBER if needed

End of User Guide