Shell integration enables advanced iTerm2 features like marks and command history tracking.

Enable Shell Integration

iTerm2 automatically installs shell integration. To manually enable:

curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash

Key Commands

Using Marks

Marks allow quick navigation between command outputs:

• Set mark: ⌘⇧M
• Jump to mark: ⌘⇧J
• Next mark: ⌘⌥.
• Previous mark: ⌘⌥/

Profiles define terminal appearance, behavior, and key mappings.

Default Profile Locations

~/Library/Application Support/iTerm2/DynamicProfiles/
~/Library/Application Support/iTerm2/scripts/

Dynamic Profile JSON Structure

{
  "Profiles": [
    {
      "Name": "My Profile",
      "Guid": "profile-guid-12345",
      "Command": "/bin/zsh",
      "Working Directory": "/Users/username",
      "Use Custom Font": true,
      "Font Name": "JetBrains Mono",
      "Font Size": 12,
      "Character Encoding": 4,
      "Color Preset Name": "Catppuccin Mocha",
      "Background Color": {
        "Red Component": 0.1,
        "Green Component": 0.1,
        "Blue Component": 0.12
      }
    }
  ]
}

Key Profile Settings

Triggers automatically execute actions when terminal output matches patterns.

Access Triggers

Profile Settings → Advanced → Triggers

Common Trigger Patterns

Available Actions

Example Trigger Setup

Pattern: npm ERR! Action: Highlight Text (Red background) Instant: Checked

iTerm2 integrates with tmux for enhanced terminal multiplexing.

Starting tmux with iTerm2

# Start new session with native iTerm2 integration
tmux -CC new-session -s main

# Attach to existing session
tmux -CC attach-session -t main

# New window in tmux session
tmux new-window -t main -n editor

Benefits of tmux Integration

• Native tab/pane support in iTerm2 UI
• Native search and copy/paste
• Profile settings applied per tmux pane
• Proper unicode and mouse support
• Automatic session persistence

tmux Dashboard

Access via: iTerm2 Menu → tmux → Dashboard

Shows all active tmux sessions with:

• Session names and window count
• Pane arrangement visualization
• Quick switch between sessions

Key Mappings

iTerm2 supports displaying images and downloading files in the terminal.

Image Display Commands

# Display image using imgcat
imgcat ~/screenshot.png

# Inline image display
printf '\e]1337;File=name=filename;size=123456;base64=1:\n'

# Download file from URL
it2dl https://example.com/image.jpg

Supported Image Formats

Image Display Features

• Inline image preview in terminal
• Click to open in default app
• Cmd+click to copy to clipboard
• Right-click for context menu
• Automatic size adjustment

it2dl - Download Utility

# Basic download
it2dl https://example.com/file.pdf

# Specify destination
it2dl https://example.com/image.jpg ~/Downloads/

# Download with custom name
it2dl --name custom.jpg https://example.com/original.jpg

Password Manager Integration

iTerm2 can auto-fill passwords from macOS Keychain:

1. Profile Settings → Advanced → Password Manager
2. Enable “Password Manager” option
3. Use keyboard shortcut to fill passwords
4. Supports SSH key passphrases

Instant Replay

Access with: ⌘⌘ (press Command twice)

• Rewind terminal history without scrollback limit
• Typical limit: last 100MB of data
• Navigate with arrow keys
• Disable with: Preferences → Advanced → Instant Replay disabled

Smart Selection

Right-click to select intelligently:

• Email addresses
• URLs
• IP addresses
• File paths
• Custom regex patterns

Define custom patterns in Preferences → Profiles → Advanced → Smart Selection Rules.

Semantic History

Cmd+click to open files referenced in terminal:

• Application configuration via Cmd+click
• Custom opener selection available
• Supports relative and absolute paths
• Protocol handler integration (ssh://, ftp://)

Status Bar

Display terminal information persistently:

• Add components: View → Toggle Status Bar
• Available indicators: hostname, git status, time, battery
• Customizable per profile
• Light/dark mode aware

Customize keyboard shortcuts for increased productivity.

Access Key Mappings

Profile Settings → Keys → Key Mappings

Common Key Mapping Examples

Hex Code Reference

0x01 = Ctrl+A (Home)
0x05 = Ctrl+E (End)
0x08 = Ctrl+H (Backspace)
0x15 = Ctrl+U (Clear line)
0x17 = Ctrl+W (Delete word)
0x1b = Escape prefix

Custom Mapping Example

Map ⌥⌫ to delete word backward:

1. Key: ⌥⌫
2. Action: Send Hex Code
3. Code: 0x17 (Ctrl+W)

Vim Mode Key Mappings

For vim-style navigation:

Badges and Titles

Set dynamic window titles in shell config:

# In ~/.zshrc
function set_title() {
  print -Pn "\e]2;$1\a"
}

# Usage
set_title "Development Server"

Arrangements

Save window layouts for quick restoration:

1. Arrange windows and panes as desired
2. Window → Save Window Arrangement
3. Restore: Window → Restore Arrangement

Buried Sessions

Hide background sessions without closing:

• Right-click session
• “Bury Session”
• Access via Window menu when needed
• Useful for long-running processes

Status Bar Customization

Add useful indicators to status bar:

• Hostname display
• Git branch/status
• Current time
• Battery percentage
• User-defined components via escape sequences

Command Palette

Quick access to iTerm2 functions:

• Press: ⌘⇧A
• Search for commands
• Recent commands prioritized
• Fully customizable

Search Enhancement

Advanced find features:

• Find in pane history: ⌘F
• Regex pattern support
• Case-sensitive toggle
• Highlight all matches
• Jump to find results with Enter

Session Logging

Enable session recording for auditing:

# Enable logging
script ~/session-$(date +%s).log

# All terminal activity recorded to file
# Exit to close logging
exit

Color Schemes

Apply Catppuccin theme:

1. Download theme files from catppuccin/iterm2
2. Preferences → Profiles → Colors
3. Color Presets → Import
4. Select Catppuccin Mocha
5. Apply to profiles

Cursor Customization

Profile Settings → Appearance → Cursor:

• Block (default)
• Underline
• Vertical Bar
• Blinking toggle
• Color customization per profile