Table of Contents

The iterm2 URL Scheme

iTerm2 registers a custom URL scheme, iterm2:, that lets other apps, scripts, links, and the open command ask iTerm2 to perform certain actions. For example, opening iterm2:reveal?sessionid=$ITERM_SESSION_ID brings a particular session to the front.

You can open one of these URLs in many ways: with open 'iterm2:...' from the shell, by clicking a link in another app, or with an OSC 8 hyperlink printed in the terminal. Most handlers are also used internally by iTerm2 itself, for instance in the messages shown by clicking the indicators at the top right of a session.

Security Model

Because any app on the system can open an iterm2: URL, these handlers are designed to be safe to trigger from an untrusted source:

  • Handlers that only reveal existing content (such as reveal, annotation, and reveal-mark) take no destructive action.
  • The command handler always shows a dialog that lets you review and edit the command before it runs, and the option to run a command silently in the background is only available for links generated by iTerm2 itself.
  • The triggers handler shows a confirmation dialog listing what will be imported and into which profiles.

The scheme name is always iterm2. Note that the exact number of slashes matters: some handlers use an opaque path like iterm2:reveal?... (no slashes) while others use a leading slash like iterm2:/command?.... Follow the exact form given for each handler below.

command

Runs a command. This is the URL created by the Share button on a selected command (see Command Selection) and by Copy Command URL to Clipboard in the Command Info panel.

A simple example is iterm2:/command?c=date. The path is always /command.

Query parameters:

  • c (required): the command to run. Leading and trailing whitespace is removed.
  • d (optional): a directory to change into before running the command.
  • silent (optional): a value-less flag requesting that the command run in the background without showing its output. This only takes effect for links generated inside iTerm2; when it applies, a confirmation dialog is shown first.

If a hostname is present, iTerm2 offers to ssh to that host to run the command. For example, iterm2://[email protected]/command?c=date runs date on example.com as user gnachman.

When you open a command URL, iTerm2 presents a window describing what will be done and lets you edit the command, directory, and ssh destination before choosing how to run it: in a new window, a new tab, or the current session.

This handler requires macOS 11 or later.

reveal

Brings a specific session to the front, searching visible tabs, buried sessions, and other windows.

iterm2:reveal?sessionid=<id>

The sessionid parameter takes the value of the session's ITERM_SESSION_ID environment variable (for example, w0t0p0:ABCD-EFGH-...). This is useful for jumping back to a session from an external script, note, or other application: record the session ID when starting a long-running job and open the URL later to return to it.

triggers

Imports one or more triggers into profiles you select. This is the URL produced when you export triggers from iTerm2.

iterm2:triggers?<trigger>&<trigger>&...

Each query parameter is a URL-encoded JSON dictionary describing one trigger, given as the parameter name with no value. When opened, iTerm2 shows a dialog listing the triggers and asks which profiles to add them to. Because of the encoding involved, these URLs are meant to be generated by iTerm2 rather than written by hand.

copy-block

Copies the text of a command block (the output of a single command, when Shell Integration is installed) to the clipboard.

iterm2:copy-block?guid=<session-guid>&block=<block-id>

Query parameters:

  • guid (optional): the GUID of the session containing the block. If omitted, the current session is used.
  • block (required): the identifier of the block to copy.

annotation

Reveals a particular annotation and brings its session to the front.

iterm2:annotation?s=<session-guid>&ann=<annotation-id>

Query parameters:

  • s (required): the GUID of the session containing the annotation.
  • ann (required): the identifier of the annotation to reveal.

reveal-mark

Scrolls to and reveals a named or prompt mark, bringing its session to the front.

iterm2:reveal-mark?s=<session-guid>&m=<mark-guid>

Query parameters:

  • s (required): the GUID of the session containing the mark.
  • m (required): the identifier of the mark to reveal.

compound-location

Reveals a selection within a session, restoring an exact range of selected text. This is used by iTerm2 to link back to a specific location.

iterm2:/compound-location?session=<session-guid>&sub=<selection>&sub=...

Query parameters:

  • session (required): the GUID of the session.
  • sub (one or more): a serialized sub-selection. Multiple sub parameters may be given to describe a discontiguous selection.