How it2 works

it2 maps a hierarchy of Cobra commands onto iTerm2's automation API. Most
commands follow the shape it2 <resource> <action>, such as
it2 session list or it2 window create.

Command dispatch

The root command registers resource groups for sessions, tabs, windows, text,
profiles, notifications, and other iTerm2 features. Cobra parses the command
path and flags, then calls the selected command's handler.

Root flags provide shared connection timeout and output-format defaults.
Individual commands may add flags for their own operation.

Connection path

Commands that need iTerm2 create a client through the shared connection
helper. With the default target, the client first checks iTerm2 automation,
then tries iTerm2's private Unix socket when it exists. It falls back to the
WebSocket endpoint at ws://localhost:1912.

Authentication credentials are sent as iTerm2 request headers when the
ITERM2_COOKIE and ITERM2_KEY environment variables are present. The client
can ask iTerm2 for credentials when it connects through the default local
path.

Session targeting

Commands that act on a session resolve the target before making the API
request. A command may accept a full session UUID, a unique case-insensitive
prefix of at least four characters, or the current session from
ITERM_SESSION_ID when that command supports an omitted target.

Explicit IDs are the safest choice in automation. Creation commands such as
it2 session split --quiet print the new ID so a script can retain and reuse
it.

Output and errors

The root --format flag selects table, text, JSON, or YAML output where a
command supports structured formatting. Commands return errors to the root,
which suppresses Cobra's automatic usage dump for runtime failures.

Long-running monitoring commands keep the API connection open and consume
notifications. One-shot commands connect, make their request, print the result,
and exit.

Source map

Next steps