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:

Check if iTerm2 API is enabled:
- iTerm2 → Preferences → General → Magic
- Enable "Enable Python API"

Verify iTerm2 is running:

# Check if iTerm2 is running
ps aux | grep iTerm2

Check WebSocket URL:

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

Test with different timeout:
```
it2 --timeout 10s session list
```

Problem: Authentication failures

Error: authentication failed

Solutions:

Allow API access when prompted:
- iTerm2 will show a dialog asking for permission
- Click "OK" to allow API access

Check authentication cookies:

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

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

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:

IT2_URL for WebSocket URL
IT2_TIMEOUT for connection timeout
IT2_FORMAT for output format
IT2_DEBUG for debug output

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:

Optimize plugin performance:
- Cache expensive operations
- Exit early for irrelevant sessions
- Use efficient commands

Test plugin timing:

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

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

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

Check if using correct session ID format:

Session IDs are typically UUIDs or iTerm2-generated strings
Don't confuse with session names

Problem: Cannot create sessions

Check profile exists:

it2 profile list

Use explicit profile:

it2 session create --profile "Default"

Check window context:

# List windows first
it2 window list

# Create in specific window
it2 session create --window-id <window-id>

Shell Integration Issues

Problem: Shell integration features not working

Error: command not found - shell integration required

Enable Shell Integration:

Install iTerm2 Shell Integration:

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

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
export IT2_DEBUG=1
it2 session list

This will show:

Plugin discovery process
WebSocket communication
Authentication steps
Timing information

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:

Completion requires active iTerm2 connection
Verify basic commands work: it2 session list

Test completion manually:

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

Log Files and Debugging

Check system logs:

macOS Console.app:

Filter for "iTerm2" or "it2"
Look for WebSocket or API related errors

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"

iTerm2 not running or API disabled
Check iTerm2 preferences for Python API

"timeout exceeded"

Increase timeout: --timeout 10s
Check network connectivity
Plugin might be hanging

"invalid session ID"

Session may have been closed
Refresh session list: it2 session list
Use tab completion for valid IDs

"profile not found"

Check available profiles: it2 profile list
Use exact profile name with quotes if needed

"permission denied"

Authentication issue
Clear auth cookies: rm -rf ~/.it2/
Restart iTerm2 and retry

Getting Help

Built-in help:

it2 --help
it2 session --help
it2 session create --help

Version information:

it2 version  # If implemented

Report issues:

Include this information when reporting bugs:

Operating system and version
iTerm2 version
it2 command that failed
Full error message
Debug output (with ITERM2_DEBUG=1)

Community resources:

Check existing issues on GitHub
Include minimal reproduction steps
Provide configuration and environment details

iTerm2 CLI