Launch a script in a new iTerm2 window

Open iTerm2 in a specific project directory, run a setup script, and drop into an interactive shell when the script finishes. The same pattern as the Ghostty example, with one parsing quirk.

The trick

iTerm2 has a --command= flag that takes a full shell line as a single value, just like Ghostty's. It's not documented on iterm2.com (only in the binary's --help output), but it's stable and works the way you'd expect.

The one difference from Ghostty: iTerm has no --working-directory= equivalent. You set the working directory yourself by cd-ing as the first thing in the command.

Working configuration

{
  "label": "Open project shell (prod)",
  "type": "command",
  "command": "open",
  "args": [
    "-na", "iTerm",
    "--args",
    "--command=cd /Users/you/Code/your-project && ./scripts/setup-env.sh prod; exec zsh -i"
  ]
}

Replace these with your own values:

• cd /Users/you/Code/your-project: absolute path to your project directory.
• ./scripts/setup-env.sh prod: your setup script and any arguments it expects.

Why this works

• open -na iTerm launches a fresh iTerm instance and forwards everything after --args to it. Direct CLI launch is not supported on macOS, same as Ghostty.
• iTerm wraps the value of --command= in /usr/bin/login -fpq $USER $SHELL -c <value>. The login part exec's your shell as a login shell, which sources your .zprofile and .zshrc automatically. Homebrew, nvm, and anything else on your normal PATH is already there. No need for a manual zsh -lc wrapper.
• The cd at the start of your command sets the working directory inside the new shell.
• exec zsh -i at the end replaces the script process with an interactive shell, so the iTerm window stays open after setup.

Variant: open a new tab in your existing iTerm window

open -na iTerm always opens a new window. If you'd rather open a new tab in your current iTerm window, drop the CLI approach and use AppleScript:

{
  "label": "Open project shell (prod)",
  "type": "applescriptFile",
  "applescriptFile": "scripts/open-iterm-tab.applescript"
}

With scripts/open-iterm-tab.applescript (resolved relative to the tool's directory):

tell application "iTerm"
  activate
  tell current window
    create tab with default profile command "/bin/zsh -lc 'cd /Users/you/Code/your-project && ./scripts/setup-env.sh prod; exec zsh -i'"
  end tell
end tell

This variant requires the Automation permission (macOS prompts you on first run) and is the only way to control tab placement.

Prerequisites

• iTerm2 installed
• zsh as your shell (default on macOS 10.15+)
• For the AppleScript variant only: Automation permission for Runyard → iTerm, in System Settings → Privacy & Security → Automation.