A few months ago, iTerm2 released a new version that included a Python API. At first I didn’t pay much attention to it until I recently tried to configure sessions using Profiles, realising that this was way easier to do when I could actually script all of this. This reminded me that there is a Python API build in into iTerm2 which could just that.
The Python API is not enabled by default, you must enable it by going to preference > magic and check “Enable Python API” and agree with the warning it gives on what this API can do.
After you have enabled the Python API you can use the menu items under the script pulldown menu. The first time you are going to use the API, iTerm2 will download a Python Runtime environment for you. After start building your scripts, the iTerm2 documentation also includes a bunch of example scripts for inspiration. iTerm2 uses a virtualenv to separate all the scripts, this also means that any non-default libraries should be added to the virtualenv.
So lets get going, I often find myself in a situation where I am opening a new session, cd to a working dir, startup vagrant, ssh into the box, open a new session and ssh as a different user into that box. I want to automate that process so I don’t have to repeat those steps every time. Here is the complete script, we will break down the most important parts:
#!/usr/bin/env python3
import iterm2
import os, subprocess
# Variables
vagrantDir = '/my/path/to/my/vagrantfile'
# extend path to find vagrant and vbox binaries
my_path=os.environ.get('PATH')
my_path = '/usr/local/bin/:' + str(my_path)
# Check Vagrant status
def vagrant_stat():
p = subprocess.check_output(['vagrant', 'status', '--machine-readable'], cwd=vagrantDir, env={"PATH": my_path})
p1 = p.decode("utf-8")
return p1
async def main(connection):
app = await iterm2.async_get_app(connection)
# Get the current Terminal window
window = app.current_terminal_window
# Make sure that we are in a iTerm2 window
if window is not None:
# Create a new tab, split panes into 2 sessions, set profiles
tab = await window.async_create_tab()
split = await tab.current_session.async_split_pane(vertical=True)
# Startup vagrant box if it is not running
vagrant_action = vagrant_stat()
if (vagrant_action.find('poweroff') != -1):
subprocess.call(['vagrant', 'up', '--machine-readable'], cwd=vagrantDir, env={"PATH": my_path})
# Change the prompt to the VagrantFile and SSH into the box
for session in tab.sessions:
await session.async_send_text(f"cd {vagrantDir}\n")
await session.async_send_text("vagrant ssh\n")
# Sudo to oracle on the left window:
await tab.sessions[0].async_send_text("sudo su - oracle\n")
# Sudo to root on the right window:
await tab.sessions[1].async_send_text("sudo -i\n")
else:
# You can view this message in the script console.
print("No current window")
iterm2.run_until_complete(main)
The first few lines are importing some libraries, with iterm2 (available on PyPi) being the obvious one, setting some variables and making sure that python can find tools look vagrant and vboxmanage. Also a helper function if I need to check later on if the vagrant box is up-and-running.
async def main(connection):
app = await iterm2.async_get_app(connection)
# Get the current Terminal window
window = app.current_terminal_window
Here we begin our main function, as you can see this uses this uses python’s asyncio libraries. Most of iTerm2’s functions are using async, which can be handy as we can continue even if we are still waiting for other steps to finish.
# Create a new tab, split panes into 2 sessions, set profiles
tab = await window.async_create_tab()
split = await tab.current_session.async_split_pane(vertical=True)
After we have defined our current iTerm2 window we can call the async_create_tab() function to create a new tab in the current window. We then will split that tab into 2 vertical session with async_split_pane()
# Startup vagrant box if it is not running
vagrant_action = vagrant_stat()
if (vagrant_action.find('poweroff') != -1):
subprocess.call(['vagrant', 'up', '--machine-readable'], cwd=vagrantDir, env={"PATH": my_path})
We then want to check if the vagrant box is actually up-and-running, if it is not then we issue a subprocess.call() to startup the box. I am using subprocess.call() here to make sure that python waits until the vagrant command is done.
# Change the prompt to the VagrantFile and SSH into the box
for session in tab.sessions:
await session.async_send_text(f"cd {vagrantDir}\n")
await session.async_send_text("vagrant ssh\n")
Vagrant is now up and we can now ssh into the box. By looping through all the sessions we can send text into the sessions as it was a user typing into the iTerm2 window.
# Sudo to oracle on the left window:
await tab.sessions[0].async_send_text("sudo su - oracle\n")
# Sudo to root on the right window:
await tab.sessions[1].async_send_text("sudo -i\n")
Finally I want to sudo the session in the vagrant box to oracle and the other session to root.
iterm2.run_until_complete(main)
Now are main function is defined, we can call the main function and let iTerm2 configure our tab, start the vagrant box, set the working dir, ssh into the box and sudo to oracle and root.
Of course this is a very simple example of what is possible with the Python API.pytho
Future Veterans 