iterm2

README

iTerm2

Go library for automating iTerm2 Scripts

Install

go get marwan.io/iterm2

Usage

package main

func main() {
    app, err := iterm2.NewApp("MyCoolPlugin")
    handle(err)
    defer app.Close()
    // use app to create or list windows, tabs, and sessions and send various commands to the terminal.
}

How do I actually run the script?

• Since you will be using this library in a "main" program, you can literally just run the Go program through "go run" or install your program/binary globally through "go install" and then run it from any terminal.

• A nicer way to run the script is to "register" the plugin with iTerm2 so you can run it from iTerm's command pallette (cmd+shift+o). This means you won't need a terminal tab open or to remember what the plugin name is. See the following section on how to do that:

• Ensure you enable the Python API: https://iterm2.com/python-api-auth.html

Installing the plugin into iTerm2

1. Install your program into your local PATH (for example running go install)
2. go get marwan.io/iterm2/cmd/goiterm
3. goiterm install <bin>
4. From any iTerm window run "cmd+shift+o" and look for <bin>.py.

Progress

This is currently a work in progress and it is a subset of what the iTerm2 WebSocket protocol provides.

I don't intend to implement all of it as I am mainly implementing only the parts that I need for daily work.

If you'd like to add more features, feel free to open an issue and a PR.

Documentation

Index

• type App
  • func NewApp(name string) (App, error)
• type Session
• type SplitPaneOptions
• type Tab
• type Window

Types

type App

type App interface {
	io.Closer

	CreateWindow() (Window, error)
	ListWindows() ([]Window, error)
	SelectMenuItem(item string) error
}

App represents an open iTerm2 application

func NewApp

func NewApp(name string) (App, error)

NewApp establishes a connection with iTerm2 and returns an App. Name is an optional parameter that can be used to register your application name with iTerm2 so that it doesn't require explicit permissions every time you run the plugin.

type Session

type Session interface {
	SendText(s string) error
	Activate(selectTab, orderWindowFront bool) error
	SplitPane(opts SplitPaneOptions) (Session, error)
	GetSessionID() string
}

Session represents an iTerm2 Session which is a pane within a Tab where the terminal is active

type SplitPaneOptions

type SplitPaneOptions struct {
	Vertical bool
}

SplitPaneOptions for customizing the new pane session. More options can be added here as needed

type Tab

type Tab interface {
	SetTitle(string) error
	ListSessions() ([]Session, error)
}

Tab abstracts an iTerm2 window tab

type Window

type Window interface {
	SetTitle(s string) error
	CreateTab() (Tab, error)
	ListTabs() ([]Tab, error)
}

Window represents an iTerm2 Window