it2 session list

List all iTerm2 sessions

Synopsis

it2 session list [flags]

Description

List iTerm2 sessions with optional filtering and output customization.

Options

--columns

Comma-separated list of columns to display (e.g., 'session id,window id,name')

--filter

Filter sessions by name or title (case-insensitive substring match)

--include-buried

Include buried sessions

--jq

Filter JSON output using a jq expression (requires --json)

--json

Output JSON with specified fields (comma-separated, or empty for all fields)

--ndjson

Output as newline-delimited JSON (one object per line)

--no-plugins

Disable plugin enrichment

--plugins

Regular expression of plugin names to run (case-sensitive)
-q, --quiet
Output only session IDs

--reverse

Reverse sort order (descending)

--scope

Filter sessions by scope (default: all sessions). Options: none, window, tab, parents, siblings, peers, lineage. Overrides IT2_SCOPE env var.

--sort

Column to sort by (e.g., 'Session ID', 'Window ID', 'Name')

--tab

Filter sessions by tab ID
-w, --wide
Show full session IDs instead of short IDs

--window

Filter sessions by window ID

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

# List all sessions in table format (default: all sessions)
$ it2 session list

# List sessions in JSON format for scripting
$ it2 session list --format json

# Output only session IDs (quiet mode)
$ it2 session list -q

# Select specific JSON fields
$ it2 session list --json id,name,cwd

# Scope filtering - only sessions in current window
$ it2 session list --scope window

# Scope filtering - only sessions in current tab
$ it2 session list --scope tab

# Filter sessions with jq (requires --json)
$ it2 session list --json id,name --jq '.[] | select(.name | test("vim"))'

# Complex jq filter: wide vim sessions in /src
$ it2 session list --json name,cwd,grid_size --jq '.[] | select(.name | test("vim") and .grid_size.width > 120 and .cwd | test("/src"))'

# Format output with jq
$ it2 session list --json id,name --jq '.[] | "\(.id): \(.name)"'

# List sessions in a specific window (by window ID)
$ it2 session list --window 1

# Filter sessions by name or title
$ it2 session list --filter vim

# List sessions with custom columns
$ it2 session list --columns id,name,title

# Sort sessions by name
$ it2 session list --sort name

# Use with xargs to send text to all sessions
$ it2 session list -q | xargs -n1 -I {} it2 session send-text {} "echo hello"

# Include buried sessions when needed
$ it2 session list --include-buried

# Count total sessions
$ it2 session list -q | wc -l