iterm2

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2026 License: GPL-2.0 Imports: 18 Imported by: 0

README

iterm2-go

A Go client for iTerm2's API — the same API its Python scripting library uses, spoken directly over the WebSocket. No Python, no bundled runtime, no script installed into iTerm2's scripts folder.

CI Go Reference

Read UPSTREAM.md before depending on this. The protocol definition is pinned and verified byte-identical to iTerm2's own. The connection to a real iTerm2 is not yet verified by any automated run — every test drives a fake that implements the protocol as read from iTerm2's source. See what is and is not verified.

Install

go get github.com/taumatix/iterm2-go@v0.1.0

Requires Go 1.27 or newer, macOS, and iTerm2 with the API enabled in Settings → General → Magic → Enable Python API. The setting's name says Python; it governs the socket, not the language.

Use

package main

import (
	"context"
	"fmt"
	"log"

	iterm2 "github.com/taumatix/iterm2-go"
)

func main() {
	ctx := context.Background()

	conn, err := iterm2.Connect(ctx, iterm2.WithAdvisoryName("my-tool"))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	h, err := conn.ListSessions(ctx)
	if err != nil {
		log.Fatal(err)
	}
	for _, s := range h.Sessions() {
		fmt.Printf("%s\t%s\n", s.ID, s.Title)
	}

	tab, err := conn.CreateTab(ctx, iterm2.CreateTabOptions{})
	if err != nil {
		log.Fatal(err)
	}
	if err := conn.SendText(ctx, tab.SessionID, "echo hello\n", false); err != nil {
		log.Fatal(err)
	}
}

The first connection raises a permission prompt in iTerm2, because the library asks the running application for a cookie over AppleScript. A program iTerm2 launched itself is handed ITERM2_COOKIE and ITERM2_KEY in its environment and is not prompted.

Watching for changes
sub, err := conn.SubscribeNewSessions(ctx)
if err != nil {
	return err
}
defer sub.Unsubscribe(ctx)

for n := range sub.C() {
	fmt.Println("new session:", n.GetNewSessionNotification().GetSessionId())
}

Notifications are dropped rather than blocking when a consumer falls behind — the read loop delivers them, so a blocked reader would stall every request on the connection. sub.Dropped() counts what was lost, and WithSubscriptionBuffer sets how much slack there is.

Anything else in the API

The hand-written surface covers the session hierarchy, sending text, creating tabs and splits, closing things, variables and notifications. Everything else iTerm2 can do — profiles, screen contents, transactions, registering a toolbelt tool — goes through Conn.Do:

resp, err := conn.Do(ctx, &apipb.ClientOriginatedMessage{
	Submessage: &apipb.ClientOriginatedMessage_RegisterToolRequest{
		RegisterToolRequest: &apipb.RegisterToolRequest{
			Name:       proto.String("My Tool"),
			Identifier: proto.String("com.example.mytool"),
			URL:        proto.String("http://localhost:8080/"),
		},
	},
})

apipb is generated from iTerm2's api.proto, so every request in the protocol is reachable without waiting for a typed wrapper here.

Errors

Error Means
ErrUnauthorized iTerm2 refused the handshake: the API is off, or the cookie was already spent. Cookies are single use.
ErrClosed The connection is gone, whether through Close or because iTerm2 quit.
*APIError iTerm2 could not parse the request, or answered with something this package cannot read.
*StatusError A well-formed request iTerm2 declined. Status carries api.proto's own spelling, so it can be looked up there.

Testing

go test ./...                       # the whole suite, no iTerm2 needed
go test -race ./...
ITERM2_LIVE=1 go test -run TestLive ./...   # against your real iTerm2: opens and closes a tab

The suite runs against internal/fakeiterm, which is not a mock of this package's internals: it listens on a real unix socket, performs a real WebSocket upgrade, checks the same handshake headers iTerm2 checks, and exchanges real protobuf. That is why it can run on Linux in CI.

What it cannot prove is that iTerm2 agrees with it, since both sides were written from the same documents by the same author. TestLive is the test that closes that gap and it has never run green — see UPSTREAM.md. Treat the connection layer as unverified against the real application.

Contributing

ROADMAP.md is ordered by how much each entry limits real use; the top of it is the next thing worth doing. Regenerating apipb/ after the protocol moves needs buf: buf generate. Never edit proto/api.proto — it is upstream's file, kept byte-identical so its digest can be checked.

License

GPL-2.0-or-later — copyleft. Linking this library into your program brings the GPL's obligations with it, so read the licence before depending on it.

This is not a preference; it follows from what the library is. proto/api.proto is copied verbatim from iTerm2, which is GPL-2.0, and iTerm2's own client bindings — the iterm2 Python package, the direct equivalent of this library — are published as GPLv2+. Relicensing a copy of someone else's protocol definition more permissively is not ours to do.

Documentation

Overview

Package iterm2 is a Go client for the iTerm2 API.

iTerm2 exposes the same API its Python scripting library uses: a WebSocket carrying protocol-buffer messages over a unix domain socket in the application's support directory. This package speaks that protocol directly, so nothing here needs Python, iTerm2's bundled runtime, or a script installed into iTerm2's scripts folder.

Enabling the API

iTerm2 rejects every connection until the API is switched on in Settings > General > Magic > Enable Python API. The name says Python; the setting governs the socket, not the language.

Connecting 

conn, err := iterm2.Connect(ctx)
if err != nil {
	return err
}
defer conn.Close()

h, err := conn.ListSessions(ctx)
if err != nil {
	return err
}
for _, s := range h.Sessions() {
	fmt.Println(s.ID, s.Title)
}

Connect authorises the connection with a single-use cookie. It reads ITERM2_COOKIE and ITERM2_KEY if they are set — which they are for a process iTerm2 launched itself — and otherwise asks the running iTerm2 for a fresh pair over AppleScript, which requires macOS. Pass WithCredentials to supply them yourself.

Two layers

The hand-written surface — Conn, Hierarchy, Window, Tab, Session and their methods — is the stable one, and covers the session hierarchy, sending text, creating tabs and splits, closing things, variables and notifications.

Everything else iTerm2 can do is reachable through Conn.Do, which sends one ClientOriginatedMessage from the apipb package and returns its response. That includes profiles, the screen contents, transactions, registering a toolbelt tool and the rest of api.proto. apipb is generated from iTerm2's api.proto and tracks it: UPSTREAM.md records the commit it came from, what is verified, and what is not.

Concurrency

A Conn is safe for concurrent use. Requests from many goroutines are serialised onto the socket and matched to their responses by message id, so one slow request does not block another.

Notifications are delivered to a Subscription's channel and are dropped rather than blocking when the consumer falls behind, because the read loop delivers them and a blocked reader would stall every request on the connection. Subscription.Dropped counts what was lost.

Index

Constants

View Source 
const (
	// Subprotocol is the WebSocket subprotocol iTerm2 requires. iTerm2 refuses
	// the upgrade unless sec-websocket-protocol matches it exactly
	// (iTermWebSocketConnection.m, kProtocolName).
	Subprotocol = "api.iterm2.com"

	// LibraryVersion is reported in the x-iterm2-library-version header as
	// "go <LibraryVersion>".
	//
	// iTerm2 requires the header to be two space-separated fields and compares
	// the second against a per-language minimum. It publishes a minimum for
	// "python" only, so "go" is not version-gated today — iTerm2's own Swift
	// client sends "swift 1.0" on the same basis. The value is a plain decimal
	// rather than this module's semantic version because that is what the
	// comparison parses; it is not a promise about anything else, and it moves
	// only if iTerm2 starts gating Go clients.
	LibraryVersion = "0.1"

	// LegacyTCPAddress is the loopback address iTerm2 listened on before the
	// unix domain socket, and still accepts. [Connect] falls back to it when the
	// socket is absent, which is what iTerm2's Python library does.
	LegacyTCPAddress = "localhost:1912"
)
View Source 
const (
	// SessionAll addresses every session at once.
	SessionAll = "all"

	// SessionActive addresses whichever session currently has keyboard focus.
	SessionActive = "active"
)

Session identifiers that iTerm2 accepts in place of a real one, documented at the top of api.proto. Not every request accepts them; the comment on each request message in api.proto says which do.

View Source 
const AllVariables = "*"

AllVariables is the name that asks for every variable in one JSON object instead of a single value, as api.proto's "special value" for the get field.

Variables

View Source 
var ErrClosed = errors.New("iterm2: connection closed")

ErrClosed is returned by every operation on a Conn whose connection has gone away, whether because Conn.Close was called or because iTerm2 quit.

View Source 
var ErrNoCredentials = errors.New("iterm2: ITERM2_COOKIE and ITERM2_KEY are not set")

ErrNoCredentials is returned by EnvCredentials when neither ITERM2_COOKIE nor ITERM2_KEY is set.

View Source 
var ErrNotSupported = errors.New("iterm2: not supported by this iTerm2")

ErrNotSupported reports a request iTerm2 understood but declined as unavailable, such as a notification type this iTerm2 version does not post.

View Source 
var ErrUnauthorized = errors.New("iterm2: unauthorized")

ErrUnauthorized wraps a handshake iTerm2 refused. The usual causes are the Python API being switched off in Settings > General > Magic, and a cookie that has already been used — iTerm2 consumes each one exactly once.

Functions

func DefaultSocketPath 

func DefaultSocketPath() string

DefaultSocketPath returns the unix domain socket a running iTerm2 listens on.

It honours IT2_SUITE, which iTerm2 uses to keep parallel builds — a nightly alongside a release — from sharing one support directory.

Types

type APIError 

type APIError struct {
	Message string
}

APIError is iTerm2's report that a request could not be understood. It corresponds to the `error` field of ServerOriginatedMessage, which iTerm2 sets only for a malformed request — never as an ordinary outcome.

func (*APIError) Error 

func (e *APIError) Error() string

type ActivateOptions 

type ActivateOptions struct {
	// OrderWindowFront raises the window containing the target.
	OrderWindowFront bool

	// SelectTab selects the target's tab. Valid for a tab or a session.
	SelectTab bool

	// SelectSession selects the target pane within its tab. Valid for a session.
	SelectSession bool

	// ActivateApp brings iTerm2 itself to the front.
	ActivateApp bool

	// RaiseAllWindows and IgnoringOtherApps apply only with ActivateApp, and
	// correspond to ActivateRequest.App in api.proto.
	RaiseAllWindows   bool
	IgnoringOtherApps bool
}

ActivateOptions asks for more than the default of bringing one object forward.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is a connection to a running iTerm2.

A Conn is safe for concurrent use: requests from many goroutines are serialised onto the socket and matched to their responses by message id.

Every method takes a context. Cancelling one abandons that request only — a response arriving afterwards is discarded. To tear the connection down, call Conn.Close.

func Connect 

func Connect(ctx context.Context, opts ...Option) (*Conn, error)

Connect dials a running iTerm2 and completes the API handshake.

It prefers the unix domain socket at DefaultSocketPath and falls back to LegacyTCPAddress when that socket does not exist, matching iTerm2's own Python library.

The API must be enabled in iTerm2 (Settings > General > Magic > Enable Python API) or the handshake fails with an error wrapping ErrUnauthorized.

func (*Conn) Activate 

func (c *Conn) Activate(ctx context.Context, opts ActivateOptions) error

Activate brings iTerm2 to the front without selecting anything in particular.

func (*Conn) Close 

func (c *Conn) Close() error

Close shuts the connection down and waits for its reader to finish.

Requests in flight fail with ErrClosed, and every Subscription channel is closed. Calling it more than once is harmless, and calling it on a connection iTerm2 already dropped returns nil.

func (*Conn) CloseSessions 

func (c *Conn) CloseSessions(ctx context.Context, force bool, ids ...string) error

CloseSessions closes panes by id.

force skips the confirmation iTerm2 would otherwise show for a session with a running job; without it, a user who declines leaves that session open and the call reports USER_DECLINED for it.

iTerm2 answers with one status per target, so closing several can partly succeed. The returned error joins one *StatusError per target that failed, naming it, and is nil only when every one closed.

func (*Conn) CloseTabs 

func (c *Conn) CloseTabs(ctx context.Context, force bool, ids ...string) error

CloseTabs closes tabs by id. See Conn.CloseSessions for force and the per-target statuses.

func (*Conn) CloseWindows 

func (c *Conn) CloseWindows(ctx context.Context, force bool, ids ...string) error

CloseWindows closes windows by id. See Conn.CloseSessions for force and the per-target statuses.

func (*Conn) CreateTab 

func (c *Conn) CreateTab(ctx context.Context, opts CreateTabOptions) (*NewTab, error)

CreateTab opens a new tab, or a new window when opts.WindowID is empty.

func (*Conn) Do 

func (c *Conn) Do(ctx context.Context, req *apipb.ClientOriginatedMessage) (*apipb.ServerOriginatedMessage, error)

Do sends one request and returns iTerm2's response to it.

This is the whole API: every request type in api.proto is a field of apipb.ClientOriginatedMessage, and the typed methods on Conn are built on this one. req is not modified — Do sends a copy carrying the message id.

A response whose `error` field is set comes back as an *APIError, because iTerm2 sets it only for a request it could not parse. Per-request status enums are left in the response for the caller to read; the typed methods turn a non-OK status into a *StatusError.

func (*Conn) GetStringVariable 

func (c *Conn) GetStringVariable(ctx context.Context, scope VariableScope, identifier, name string) (value string, ok bool, err error)

GetStringVariable reads one variable and decodes it as a string.

It returns ok false when the variable is unset. A variable holding something other than a string — a number, or the object AllVariables returns — is an error, because silently rendering it would hide the mismatch.

func (*Conn) GetVariables 

func (c *Conn) GetVariables(ctx context.Context, scope VariableScope, identifier string, names ...string) (map[string]json.RawMessage, error)

GetVariables reads variables from one object.

identifier names the session, tab or window, and is ignored for ScopeApp. The returned values are JSON, exactly as iTerm2 sends them: a string variable arrives quoted. Use Conn.GetStringVariable when a string is what is wanted.

The result is keyed by the requested name and omits any variable iTerm2 reported as unset, which it does by sending JSON null.

iTerm2 refuses to read more than one variable at once from SessionAll and answers MULTI_GET_DISALLOWED.

func (*Conn) ListSessions 

func (c *Conn) ListSessions(ctx context.Context) (*Hierarchy, error)

ListSessions returns a snapshot of every window, tab and session.

func (*Conn) SendText 

func (c *Conn) SendText(ctx context.Context, sessionID, text string, suppressBroadcast bool) error

SendText types text into the session, as though the user had.

The session may be SessionAll or SessionActive. suppressBroadcast keeps the text out of other sessions when the user has broadcasting switched on.

func (*Conn) SetStringVariable 

func (c *Conn) SetStringVariable(ctx context.Context, scope VariableScope, identifier, name, value string) error

SetStringVariable writes one string variable, doing the JSON quoting.

The name must begin with "user." — see Conn.SetVariables.

func (*Conn) SetVariables 

func (c *Conn) SetVariables(ctx context.Context, scope VariableScope, identifier string, values map[string]string) error

SetVariables writes variables on one object.

Values must be JSON, so a string needs its quotes. iTerm2 rejects any name not beginning with "user." and answers INVALID_NAME, which arrives as a *StatusError: the built-in variables are iTerm2's to write, not a script's.

func (*Conn) SplitPane 

func (c *Conn) SplitPane(ctx context.Context, sessionID string, opts SplitPaneOptions) ([]string, error)

SplitPane divides a session and returns the ids of the sessions created.

More than one id comes back when sessionID is SessionAll. api.proto warns that a tmux integration session reports none, because the split happens only if and when the tmux server acts on it.

func (*Conn) Subscribe 

func (c *Conn) Subscribe(ctx context.Context, req *apipb.NotificationRequest) (*Subscription, error)

Subscribe asks iTerm2 to post notifications and returns them on a channel.

req must set NotificationType. Everything else api.proto allows — the session to watch, a VariableMonitorRequest, a KeystrokePattern filter — is passed through untouched, so this covers notification types this package has no named helper for. Subscribe sets Subscribe itself.

The returned Subscription must be released with Subscription.Unsubscribe, or iTerm2 keeps posting for the life of the connection.

func (*Conn) SubscribeFocusChanges 

func (c *Conn) SubscribeFocusChanges(ctx context.Context) (*Subscription, error)

SubscribeFocusChanges posts a notification when the application, window, tab or pane with focus changes. api.proto warns that duplicates are normal; ignore the ones that report no change.

func (*Conn) SubscribeLayoutChanges 

func (c *Conn) SubscribeLayoutChanges(ctx context.Context) (*Subscription, error)

SubscribeLayoutChanges posts a notification whenever windows, tabs or panes move. Each carries a full hierarchy snapshot, the same shape Conn.ListSessions returns.

func (*Conn) SubscribeNewSessions 

func (c *Conn) SubscribeNewSessions(ctx context.Context) (*Subscription, error)

SubscribeNewSessions posts a notification whenever a session is created, or a closed one is restored by undo. Read the id from apipb.Notification.GetNewSessionNotification.

func (*Conn) SubscribeTerminatedSessions 

func (c *Conn) SubscribeTerminatedSessions(ctx context.Context) (*Subscription, error)

SubscribeTerminatedSessions posts a notification whenever a session ends.

func (*Conn) SubscribeVariableChanges 

func (c *Conn) SubscribeVariableChanges(ctx context.Context, scope VariableScope, identifier, name string) (*Subscription, error)

SubscribeVariableChanges posts a notification when a variable changes.

identifier names the session, tab or window to watch and is ignored for ScopeApp. name is the variable, such as "jobName" or "user.myVariable".

type CreateTabOptions 

type CreateTabOptions struct {
	// ProfileName selects the profile. Empty uses the default profile.
	ProfileName string

	// WindowID puts the tab in an existing window. Empty creates a new window.
	WindowID string

	// TabIndex is the position for the new tab, and is valid only with WindowID.
	// nil lets iTerm2 choose. An index iTerm2 cannot honour still creates the
	// tab — it answers INVALID_TAB_INDEX, which arrives as a [*StatusError]
	// even though the tab now exists.
	TabIndex *uint32

	// SelectTab, when pointed at false, creates the tab in the background
	// without selecting it or raising its window. nil keeps iTerm2's default of
	// selecting it.
	SelectTab *bool

	// CustomProfileProperties overrides profile settings for this session only.
	// Each value must be JSON, matching ProfileProperty.json_value in
	// api.proto — a string setting therefore needs its quotes, as in
	// `{"Command": "\"/bin/zsh\""}`.
	CustomProfileProperties map[string]string
}

CreateTabOptions configures Conn.CreateTab.

It is a struct rather than a list of functional options so that a field added later is an additive change for callers who construct it with field names.

type CredentialSource 

type CredentialSource interface {
	Credentials(ctx context.Context) (Credentials, error)
}

CredentialSource supplies credentials for one connection attempt.

It is called once per attempt rather than once per Conn, because a cookie is consumed by the attempt whether or not the attempt succeeds.

func AppleScriptCredentials 

func AppleScriptCredentials(advisoryName string) CredentialSource

AppleScriptCredentials asks a running iTerm2 for a fresh single-use cookie.

advisoryName is shown to the user in iTerm2's script console and in the permission prompt, so it should name the program rather than the library.

This requires macOS and a running iTerm2: it drives /usr/bin/osascript, and on any other platform it fails without running anything. The user may be asked to approve the connection the first time a given key appears.

IT2_APP_PATH, if set, selects which iTerm2 build to ask — matching the behaviour of iTerm2's own it2 CLI, and needed only when several are running.

func DefaultCredentials 

func DefaultCredentials(advisoryName string) CredentialSource

DefaultCredentials uses the environment when iTerm2 has provided credentials there, and otherwise asks iTerm2 for a fresh cookie over AppleScript.

func EnvCredentials 

func EnvCredentials() CredentialSource

EnvCredentials reads ITERM2_COOKIE and ITERM2_KEY from the environment.

iTerm2 sets both for processes it launches itself, including scripts run from its Scripts menu. It returns ErrNoCredentials when neither is set, so it can be chained ahead of AppleScriptCredentials — which is what DefaultCredentials does.

func StaticCredentials 

func StaticCredentials(cookie, key string) CredentialSource

StaticCredentials returns a source that always yields the same values.

Because a cookie is single use, a Conn built on this source can connect once. It is meant for a process iTerm2 launched — which is handed a cookie in its environment — and for tests.

type CredentialSourceFunc 

type CredentialSourceFunc func(ctx context.Context) (Credentials, error)

CredentialSourceFunc adapts a function to CredentialSource.

func (CredentialSourceFunc) Credentials 

func (f CredentialSourceFunc) Credentials(ctx context.Context) (Credentials, error)

Credentials calls f.

type Credentials 

type Credentials struct {
	Cookie string
	Key    string
}

Credentials authorise a connection to iTerm2's API.

The cookie is single use: iTerm2 consumes it during the WebSocket handshake (iTermWebSocketCookieJar consumeCookie), so a second connection needs a second cookie. The key is a stable identity for the client — iTerm2 reuses it to recognise a reconnecting script and offer the same authorisation, and invents one if it is absent.

type Hierarchy 

type Hierarchy struct {
	Windows []*Window

	// BuriedSessions are sessions iTerm2 is holding without a tab. They have no
	// frame or grid size, and no tab or window to reach them through.
	BuriedSessions []*Session
}

Hierarchy is a snapshot of every window, tab and session iTerm2 had open when Conn.ListSessions was called.

It is a snapshot, not a live view: sessions open and close, so an id taken from here can be gone by the time it is used. Requests naming a vanished session come back as a *StatusError with a NOT_FOUND status.

func (*Hierarchy) Session 

func (h *Hierarchy) Session(id string) *Session

Session finds a session by id, returning nil when the snapshot has no such session.

func (*Hierarchy) Sessions 

func (h *Hierarchy) Sessions() []*Session

Sessions returns every session in the hierarchy, buried ones last.

It is the flat view most callers want: finding a session by its title or a variable does not usually care which window it is in.

func (*Hierarchy) Tab 

func (h *Hierarchy) Tab(id string) *Tab

Tab finds a tab by id, returning nil when the snapshot has no such tab.

func (*Hierarchy) Tabs 

func (h *Hierarchy) Tabs() []*Tab

Tabs returns every tab in the hierarchy.

func (*Hierarchy) Window 

func (h *Hierarchy) Window(id string) *Window

Window finds a window by id, returning nil when the snapshot has no such window.

type NewTab 

type NewTab struct {
	WindowID string

	// TabID is rendered as a decimal string because that is the form the rest of
	// the API uses: api.proto types CreateTabResponse.tab_id as int32 while
	// ListSessionsResponse.Tab.tab_id is a string. That the two are the same
	// namespace is inferred from api.proto, not yet confirmed against a running
	// iTerm2 — see ROADMAP.md.
	TabID string

	SessionID string
}

NewTab identifies what Conn.CreateTab created.

type Option 

type Option func(*config)

Option configures Connect.

func ForceTCP 

func ForceTCP() Option

ForceTCP connects over loopback TCP even when a unix socket exists.

func WithAdvisoryName 

func WithAdvisoryName(name string) Option

WithAdvisoryName sets the name iTerm2 shows for this client in its script console and its authorisation prompt. It should name the program, not this library. The default is the running program's filename.

func WithCredentialSource 

func WithCredentialSource(src CredentialSource) Option

WithCredentialSource replaces how credentials are obtained. The default is DefaultCredentials.

func WithCredentials 

func WithCredentials(cookie, key string) Option

WithCredentials supplies a cookie and key directly, instead of reading the environment or asking iTerm2 over AppleScript. Use it when something else in the program already holds a cookie, and in tests.

func WithSocketPath 

func WithSocketPath(path string) Option

WithSocketPath overrides the unix domain socket to connect to. The default is DefaultSocketPath.

func WithSubscriptionBuffer 

func WithSubscriptionBuffer(n int) Option

WithSubscriptionBuffer sets how many notifications a Subscription buffers before it starts dropping them. The default is 64.

Notifications are dropped rather than blocking, because iTerm2 posts screen updates and keystrokes faster than most consumers read them, and a blocked reader would stall every other request on the connection. See Subscription.Dropped.

func WithTCPAddress 

func WithTCPAddress(addr string) Option

WithTCPAddress overrides the loopback address used when no unix socket is present. The default is LegacyTCPAddress.

type Rect 

type Rect struct {
	X      int32
	Y      int32
	Width  int32
	Height int32
}

Rect is a position and size in screen points, as iTerm2 reports window and pane frames.

type Session 

type Session struct {
	ID    string
	Title string

	// Frame and GridSize are unset for a buried session, because it is not on
	// screen to have either.
	Frame    Rect
	GridSize Size

	// Buried reports whether iTerm2 is holding this session without a tab.
	Buried bool
	// contains filtered or unexported fields
}

Session is one pane.

func (*Session) Activate 

func (s *Session) Activate(ctx context.Context, opts ActivateOptions) error

Activate selects this session and, with ActivateOptions, raises its tab, window and application.

func (*Session) Close 

func (s *Session) Close(ctx context.Context, force bool) error

Close closes this pane.

func (*Session) SendText 

func (s *Session) SendText(ctx context.Context, text string) error

SendText types text into this session.

func (*Session) SetVariable 

func (s *Session) SetVariable(ctx context.Context, name, value string) error

SetVariable writes one of this session's variables. The name must begin with "user.".

func (*Session) SplitPane 

func (s *Session) SplitPane(ctx context.Context, opts SplitPaneOptions) ([]string, error)

SplitPane divides this session.

func (*Session) Variable 

func (s *Session) Variable(ctx context.Context, name string) (string, bool, error)

Variable reads one of this session's variables as a string, such as "jobName", "path" or "user.something".

type Size 

type Size struct {
	Width  int32
	Height int32
}

Size is a width and height in character cells.

type SplitDirection 

type SplitDirection int32

SplitDirection is which way a pane divides. 

const (
	// SplitVertical puts the new pane beside the old one, divided by a vertical
	// line. api.proto names the divider, not the arrangement.
	SplitVertical SplitDirection = SplitDirection(apipb.SplitPaneRequest_VERTICAL)

	// SplitHorizontal puts the new pane above or below the old one.
	SplitHorizontal SplitDirection = SplitDirection(apipb.SplitPaneRequest_HORIZONTAL)
)

type SplitPaneOptions 

type SplitPaneOptions struct {
	Direction SplitDirection

	// Before puts the new pane above or to the left of the one being split.
	Before bool

	// ProfileName selects the profile. Empty uses the default profile.
	ProfileName string

	// CustomProfileProperties overrides profile settings for the new session
	// only. Values are JSON; see [CreateTabOptions.CustomProfileProperties].
	CustomProfileProperties map[string]string
}

SplitPaneOptions configures Conn.SplitPane.

type StatusError 

type StatusError struct {
	Op     string
	Status string
	Code   int32
}

StatusError reports a well-formed request that iTerm2 declined, carrying the status enum it answered with.

Op names the operation as this package spells it, so the error reads in Go terms; Status is iTerm2's own enum value name, so it can be looked up in api.proto.

func (*StatusError) Error 

func (e *StatusError) Error() string

type Subscription 

type Subscription struct {
	// contains filtered or unexported fields
}

Subscription delivers one kind of notification from iTerm2.

iTerm2 posts every notification a connection has subscribed to down the one socket, with nothing tying a notification back to the request that asked for it. A Subscription therefore remembers what it asked for and delivers only the notifications that match, so two subscriptions on one Conn do not see each other's traffic.

iTerm2 refuses a second subscription to the same notification type and session on one connection, answering ALREADY_SUBSCRIBED; Conn.Subscribe surfaces that as a *StatusError. Fan one Subscription out in your own code, or use a second Conn.

func (*Subscription) C 

func (s *Subscription) C() <-chan *apipb.Notification

C is the channel notifications arrive on. It is closed when the subscription ends, whether through Subscription.Unsubscribe or because the connection went away.

func (*Subscription) Dropped 

func (s *Subscription) Dropped() uint64

Dropped counts notifications discarded because the buffer was full. A non-zero value means the consumer is slower than iTerm2 is posting; see WithSubscriptionBuffer.

func (*Subscription) Unsubscribe 

func (s *Subscription) Unsubscribe(ctx context.Context) error

Unsubscribe tells iTerm2 to stop posting this notification and closes Subscription.C.

The channel is closed even when the request fails — there is nothing left to deliver either way — so the returned error reports what iTerm2 said and is safe to log rather than handle. Calling it twice is harmless.

type Tab 

type Tab struct {
	ID string

	// WindowID is the window this tab was found in. api.proto does not carry it
	// on the tab; it is filled in from the enclosing window while parsing, so
	// that a *Tab is usable on its own.
	WindowID string

	// ActiveSessionID is the pane with focus within this tab. Reported from
	// protocol 1.18; empty on older versions.
	ActiveSessionID string

	// TmuxWindowID and TmuxConnectionID are set only for a tab belonging to a
	// tmux integration session.
	TmuxWindowID     string
	TmuxConnectionID string

	// Group describes the tab group this tab belongs to, or nil when it belongs
	// to none. Reported from protocol 1.19.
	Group *TabGroup

	// Sessions are the tab's panes, flattened from api.proto's split tree in
	// left-to-right, top-to-bottom order. The tree's shape is not exposed yet;
	// see ROADMAP.md.
	Sessions []*Session

	// MinimizedSessions are panes the user has collapsed. They are not in
	// Sessions.
	MinimizedSessions []*Session
	// contains filtered or unexported fields
}

Tab is one tab within a window.

func (*Tab) Activate 

func (t *Tab) Activate(ctx context.Context, opts ActivateOptions) error

Activate selects this tab.

func (*Tab) ActiveSession 

func (t *Tab) ActiveSession() *Session

ActiveSession returns the tab's focused pane, or nil when iTerm2 did not say which it is — which is what an iTerm2 older than protocol 1.18 does.

func (*Tab) Close 

func (t *Tab) Close(ctx context.Context, force bool) error

Close closes this tab and every pane in it.

type TabGroup 

type TabGroup struct {
	ID string

	Name string

	// Color is a hex string as iTerm2 produces it: "#rrggbb" for sRGB, or
	// "p3#rrggbbrrggbb" for Display P3.
	Color string

	Collapsed bool
}

TabGroup is the group a tab belongs to.

A group has no central record in iTerm2: its identity is a UUID carried by each member tab, and every member reports the same name, colour and collapsed state. Two tabs are in the same group exactly when their IDs match.

type VariableScope 

type VariableScope int32

VariableScope selects which object a variable belongs to.

The values mirror api.proto's VariableScope enum, which starts at 1 — there is no zero value, so a VariableScope left at its Go zero is invalid and the methods taking one reject it rather than defaulting to a scope the caller did not choose. 

const (
	ScopeSession VariableScope = VariableScope(apipb.VariableScope_SESSION)
	ScopeTab     VariableScope = VariableScope(apipb.VariableScope_TAB)
	ScopeWindow  VariableScope = VariableScope(apipb.VariableScope_WINDOW)
	ScopeApp     VariableScope = VariableScope(apipb.VariableScope_APP)
)

func (VariableScope) String 

func (s VariableScope) String() string

String names the scope as api.proto spells it.

type Window 

type Window struct {
	ID     string
	Number int32
	Frame  Rect

	// SelectedTabID is the tab on top. iTerm2 began reporting it in protocol
	// 1.18 and leaves it empty on older versions.
	SelectedTabID string

	Tabs []*Tab
	// contains filtered or unexported fields
}

Window is one iTerm2 window.

func (*Window) Activate 

func (w *Window) Activate(ctx context.Context, opts ActivateOptions) error

Activate brings this window forward.

func (*Window) Close 

func (w *Window) Close(ctx context.Context, force bool) error

Close closes this window.

Source Files

View all Source files

Directories

Path Synopsis
internal
fakeiterm
Package fakeiterm is a stand-in for a running iTerm2, used by this module's tests.
 Package fakeiterm is a stand-in for a running iTerm2, used by this module's tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.