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.

The session-id is required and can be a full UUID or partial ID (4+ characters).

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.

Session Context Logging:
Each send-text command outputs a structured log line to stderr showing source and destination:
[it2:send-text src= dst=]
This helps debug cross-session automation and prevents accidentally sending to the wrong session.

Exit Codes:
0 - Success (text delivered and confirmed)
1 - Error (connection failure, invalid arguments, self-send without --allow-self)
2 - Partial delivery (some text delivered, retryable with --retry)
3 - No delivery (session busy/modal, retryable with --retry)
4 - Modal detected (not safe to send)

Troubleshooting:
If you see "⚠ Text partially delivered" warnings:

  1. Use --skip-confirm to bypass verification (faster, no false positives)
  2. Use --retry 3 to automatically retry on transient failures
  3. Use --require is-at-prompt,has-no-partial-input to ensure session is ready
  4. Set IT2_DEBUG_DELIVERY=1 to see detailed delivery diagnostics

Options

--allow-self

Allow sending text to the same session (disabled by default for safety)

--confirm

Prompt for confirmation before sending text

--delay-before-terminator (default "90ms")

Delay before sending line terminator
-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
-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

--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

See Also

Examples

# 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'

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

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

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

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

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

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

# Retry on transient failures (exits 2 or 3)
$ it2 session send-text 7AA9 --retry 3 --retry-delay 2s 'command'

# Skip confirmation for speed (when you don't need verification)
$ it2 session send-text 7AA9 --skip-confirm 'command'

# Debug delivery issues
$ IT2_DEBUG_DELIVERY=1 it2 session send-text 7AA9 'test'

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

# Send from stdin
$ printf '\\r' | it2 session send-text 7AA9 -

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

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

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

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

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

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

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

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

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