it2 session split

Split a session pane

Synopsis

it2 session split [<session-id>] [flags]

Description

Split a session pane horizontally or vertically, creating a new session.

If no session-id is provided, uses -s/--session flag, then $ITERM_SESSION_ID environment variable.
If neither --horizontal nor --vertical is specified, automatically chooses based on
session dimensions: vertical split when width > height, horizontal otherwise.

NOTE: The new pane is positioned adjacent to the session being split. When splitting
the same session twice, the second new pane appears next to the original session,
not next to the first split. Use --before flag or split from newly created sessions
to control positioning.

Options

--badge

Set badge text on new session(s)

--before

Create new pane before the current one

--command

Command to run in the new session

--cwd

Working directory for the new session (defaults to caller's CWD)

--horizontal

Split horizontally

--profile

Profile name for the new session (optional, uses default if not specified)
-q, --quiet
Only output the new session ID (for scripting)
-s, --session
Target session ID (alternative to positional arg)
-v, --vertical
Split vertically

Options inherited from parent commands

--format (default "text")

Output format (text, json, yaml) - affects how command results are displayed

--timeout

Timeout for API operations - how long to wait for iTerm2 to respond

--url

WebSocket URL for iTerm2 API - typically ws://localhost:1912 for local iTerm2

See Also

Examples

# Split current session (auto-detects best direction)
$ it2 session split

# Split current session vertically
$ it2 session split -v

# Split specific session horizontally using -s flag
$ it2 session split -s SESSION-ID --horizontal

# Split specific session horizontally (positional arg)
$ it2 session split SESSION-ID --horizontal

# Split with badge text
$ it2 session split --badge "Build"

# Split and just output the new session ID (for scripting)
$ it2 session split --quiet

# Split and run a command in the new session
$ it2 session split -v --command "ssh vm1"

# Split with a specific working directory
$ it2 session split --cwd /path/to/project

# Create left-right layout: use --before for left, default for right
$ LEFT=$(it2 session split -v --before)
$ RIGHT=$(it2 session split -v)
# Result: [LEFT] [ORIGINAL] [RIGHT]