it2 session send-text

Send text to a session as if typed

Synopsis

it2 session send-text [<session-id>] <text> [flags]

Description

Send text to a session as if typed.

If no session-id is provided, uses $ITERM_SESSION_ID environment variable.

By default, sends a carriage return (\r) after the text to execute commands.
Use --skip-newline to send text without any line terminator.
Use --send-lf to send line feed (\n) to move to new line without executing.

Pre-conditions:
The --require flag allows checking pre-conditions before sending text.
This is useful for automation to ensure the session is ready.
Multiple conditions can be specified and all must pass.

Examples

Basic Usage

# Send to current session (uses $ITERM_SESSION_ID)
$ it2 session send-text 'hello world'

# Send to specific session (full UUID)
$ it2 session send-text 7AA97682-C080-4D65-8C19-FDEF4669AA84 'hello world'

# Send using partial session ID (4+ characters, case-insensitive)
$ it2 session send-text 7AA9 'hello world'
$ it2 session send-text 6b1a 'test message'

Line Terminators

# Send text without any line terminator
$ it2 session send-text --skip-newline 'partial text'

# Send command with carriage return for execution
$ it2 session send-text --send-return 'ls -la'

Pre-conditions

# Wait for session to have no partial input before sending
$ it2 session send-text --require has-no-partial-input 'ls -la'

# Multiple pre-conditions (comma-separated)
$ it2 session send-text --require is-at-prompt,has-no-partial-input 'pwd'

# Multiple pre-conditions (multiple flags or comma-separated)
$ it2 session send-text --require is-at-prompt --require has-no-partial-input --require-timeout 30s 'pwd'

# Multiple conditions for Claude sessions
$ it2 session send-text --require is-claude-session,is-at-prompt,is-at-empty-prompt,has-no-queued-messages 'your command'

File Input

# Send from file
$ it2 session send-text -f file.txt

# Send from stdin
$ echo 'hello world' | it2 session send-text -f -

Special Characters

# Send escape character (for vim, etc.)
$ it2 session send-text $'\x1b'

# Send control characters
$ it2 session send-text $'\x03'  # Ctrl+C
$ it2 session send-text $'\x04'  # Ctrl+D

Vim Commands

# Send vim commands with escape
$ it2 session send-text $'\x1b:w\n'  # ESC + :w + Enter

# Send vim commands with force quit
$ it2 session send-text $'\x1b:q\x21\n'  # ESC + :q! + Enter

# Alternative methods for exclamation mark
$ it2 session send-text ':q!'         # Single quotes protect
$ it2 session send-text ':q\!'        # Backslash escape

Templates

# Template wrapping for structured messaging
$ it2 session send-text --template '<msg from="{{.ShortID}}">{{.Content}}</msg>' "hello"

# JSON formatting with timestamp
$ it2 session send-text --template '{"text":"{{.Content}}","session":"{{.SessionID}}","ts":"{{.Timestamp}}"}' "status update"

# XML message with metadata
$ it2 session send-text --template '<message session="{{.ShortID}}" time="{{.Timestamp}}">{{.Content}}</message>' "deploy complete"

# Simple prefix/suffix wrapping
$ it2 session send-text --template '[{{.ShortID}}] {{.Content}}' "log message"

Options

--confirm: Prompt for confirmation when using implicit session ID ($ITERM_SESSION_ID)
--delay-before-terminator: Delay before sending line terminator
--dry-run: Show what would be affected without executing
-f, --file: Read text from file (use '-' for stdin)
--require: Pre-condition plugins to check before sending (comma-separated or multiple flags, e.g., 'is-at-prompt,has-no-partial-input')
--require-timeout (default "10s"): Timeout for pre-condition checks
--retry (default 0): Number of retry attempts for failed deliveries (only retries on exit codes 2 and 3)
--retry-delay (default "1s"): Delay between retry attempts
--scope: Override IT2_SCOPE env var (none,window,tab,parents,siblings,peers,lineage)
-r, --send-cr (default true): Send carriage return (\r) to execute command (enabled by default)
--send-lf: Send line feed (\n) to move to new line
--skip-confirm: Skip text delivery confirmation (confirmation is enabled by default)
--skip-newline: Don't send any line terminator
--stop-on-error: Stop on first error instead of continuing
--template: Go text/template to wrap the text (variables: Content, SessionID, ShortID, Timestamp)
--verbose: Print pre-condition status messages

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

iTerm2 CLI