it2 Troubleshooting Guide

Common issues and solutions when using the it2 CLI tool.

Connection Issues

Problem: "failed to connect" error

Error: failed to connect: websocket: bad handshake

Solutions:

  1. Check if iTerm2 API is enabled:

    • iTerm2 → Preferences → General → Magic
    • Enable "Enable Python API"

  2. Verify iTerm2 is running:

    # Check if iTerm2 is running
ps aux | grep iTerm2

  3. Check WebSocket URL:

    # Default URL should work for local iTerm2
it2 --url ws://localhost:1912 session list

  4. Test with different timeout:

    it2 --timeout 10s session list

Problem: Authentication failures

Error: authentication failed

Solutions:

  1. Allow API access when prompted:

    • iTerm2 will show a dialog asking for permission
    • Click "OK" to allow API access

  2. Check authentication cookies:

    # Check if auth cookies exist
ls -la ~/.it2/

# Remove and retry if corrupted
rm -rf ~/.it2/
it2 session list

  3. Manual authentication:

    it2 auth request

Configuration Issues

Problem: Config file not being used

Check config location:

it2 config path

Verify config contents:

it2 config show

Create default config:

it2 config init

Problem: Environment variables not working

Check variable names:

Test with explicit values:

IT2_URL=ws://localhost:1912 it2 session list

Plugin Issues

Problem: Plugin not working/discovered

Check plugin discovery:

# Enable debug to see plugin discovery
export ITERM2_DEBUG=1
it2 session list

Verify plugin in PATH:

# Check if plugin is executable and in PATH
which it2-session-myplugin
ls -la $(which it2-session-myplugin)

Test plugin directly:

# Test with sample arguments
./it2-session-myplugin "test-session" "test-name"
echo $?  # Should be 0

Problem: Plugin timeout

Plugins have a 5-second timeout. To fix:

  1. Optimize plugin performance:

    • Cache expensive operations
    • Exit early for irrelevant sessions
    • Use efficient commands

  2. Test plugin timing:

    time ./it2-session-myplugin "session-id" "session-name"

  3. Add timeout handling to plugin:

    #!/bin/bash
# Add timeout to external commands
timeout 3s some-expensive-command

Output Format Issues

Problem: JSON output malformed

Use proper format flag:

it2 --format json session list

Validate JSON output:

it2 --format json session list | jq '.'

Problem: Table formatting issues

For wide tables:

# Use text format for better readability
it2 --format text session list

# Or pipe to less
it2 session list | less -S

For custom formatting:

# Use YAML for human-readable structure
it2 --format yaml session list

send-text Delivery Issues

Problem: "Text partially delivered" warnings

⚠ Text partially delivered (some characters may be missing)

Understanding exit codes:

Solutions:

  1. Enable automatic retry on transient failures:

    it2 session send-text SESSION_ID --retry 3 --retry-delay 2s "command"

  2. Wait for session to be ready before sending:

    it2 session send-text SESSION_ID --require is-at-prompt,has-no-partial-input "command"

  3. Debug delivery confirmation:

    IT2_DEBUG_DELIVERY=1 it2 session send-text SESSION_ID "test"

    This shows exactly what text is being matched and why delivery confirmation succeeds or fails.

  4. Combine readiness checks and retries:

    it2 session send-text SESSION_ID \
  --require is-at-prompt \
  --retry 3 \
  --retry-delay 2s \
  "make build"

  5. Disable confirmation only when another mechanism verifies delivery:

    it2 session send-text SESSION_ID --skip-confirm "command"

A partial-delivery status means confirmation could not prove that all text
arrived. Inspect the session with it2 session get-screen before suppressing
confirmation, or arrange an explicit completion callback from the target.

Problem: Text not appearing in session

Check session state:

# Get current screen contents
it2 session get-screen SESSION_ID

# Check if session is at a prompt
it2 session send-text SESSION_ID --require is-at-prompt --verbose "test"

Common causes:

Solutions:

# Wait for session to be ready
it2 session send-text SESSION_ID --require has-no-partial-input "command"

# Check for specific session states
it2 session send-text SESSION_ID \
  --require is-at-prompt,has-no-partial-input \
  --require-timeout 30s \
  "command"

Session Management Issues

Problem: Session ID not found

Error: session not found

Check session exists:

it2 session list

Use session completion:

# Enable shell completion first
it2 completion bash | source

# Then use tab completion
it2 session focus <TAB>

Check if using correct session ID format:

Problem: Cannot create sessions

Check profile exists:

it2 profile list

Use explicit profile when creating a tab or split:

it2 tab create "Default"
it2 session split --profile "Default"

Check window context:

# List windows first
it2 window list

# Focus specific window
it2 window focus <window-id>

Shell Integration Issues

Problem: Shell integration features not working

Error: command not found - shell integration required

Enable Shell Integration:

  1. Install iTerm2 Shell Integration:

    curl -L https://iterm2.com/shell_integration/install_shell_integration_and_utilities.sh | bash

  2. Restart your shell or source the integration:

    source ~/.iterm2_shell_integration.bash  # or .zsh

Verify integration is working:

# Check if environment variable is set
echo $ITERM_SESSION_ID

# Test shell integration commands
it2 prompt list

Performance Issues

Problem: Commands are slow

Use shorter timeouts for testing:

it2 --timeout 1s session list

Disable plugins temporarily:

# Move plugins out of PATH temporarily
mkdir ~/plugins-backup
mv ~/.local/bin/it2-* ~/plugins-backup/

Check network connectivity:

# Test WebSocket connection directly
nc -z localhost 1912

Debug Mode

Enable comprehensive debugging:

export ITERM2_DEBUG=1
it2 session list

This will show:

Increase verbosity:

it2 --format text session list 2>&1 | tee debug.log

Shell Completion Issues

Problem: Completion not working

Install completion for your shell:

Bash:

it2 completion bash > ~/.it2-completion.bash
echo "source ~/.it2-completion.bash" >> ~/.bashrc
source ~/.bashrc

Zsh:

it2 completion zsh > ~/.it2-completion.zsh
echo "source ~/.it2-completion.zsh" >> ~/.zshrc
source ~/.zshrc

Fish:

it2 completion fish > ~/.config/fish/completions/it2.fish

Problem: Completion shows no results

Check iTerm2 connection:

Test completion manually:

# Should show available sessions
it2 session activate <TAB><TAB>

Log Files and Debugging

Check system logs:

macOS Console.app:

Command line logs:

# iTerm2 logs
log show --predicate 'process == "iTerm2"' --last 1h

# System WebSocket logs
log show --predicate 'message CONTAINS "websocket"' --last 1h

it2 debug output:

Save debug output for analysis:

ITERM2_DEBUG=1 it2 session list > debug-output.log 2>&1

Common Error Messages

"connection refused"

"timeout exceeded"

"invalid session ID"

"profile not found"

"permission denied"

Getting Help

Built-in help:

it2 --help
it2 session --help
it2 session split --help

Version information:

it2 version

Report issues:

Include this information when reporting bugs:

Community resources:

Next steps