How do I get and set the titles of the window, tab, and session in iTerm 2 (with the API)?

Question

I've been looking through the documentation for iTerm2's Python API, trying to figure out a way to get and set the names/titles of

windows,
tabs, and
sessions.

I've also experimented in an iTerm Python REPL, to no avail.

Window title seems to still be settable with the old shell escape codes, e.g. using a function like this:

window_title() {
    echo -ne "\e]2;$@\a\e]1;$@\a"
}

But I can't even find alternative ways of setting the session title or the tab title, much less doing so through the Python API.

The relationship between window title, tab title, and session title can be more clearly seen if you look at its effects (assuming session title is set to show the session name--a distinction that can be confusing if they are not set to be the same).

Ahh... the beta interface...thought you were talking about one of the 3rd-party python libs are are floating around.... in that case checkout using RPC: https://iterm2.com/python-api/examples/georges_title.html — SushiHangover, May 10 '19 at 03:11
@SushiHangover: thanks for the tip, that looks like some interesting code. However it doesn't run as advertised, so I'm reluctant to try to copy anything from it when there's a missing link somewhere and I have no idea where... — iconoclast, May 11 '19 at 01:20
You should post an issue over on George's iTerm repo: https://gitlab.com/gnachman/iterm2/issues If the docs are out of sync/not working (I believe there is a python API Doc repo also but I do no have a link...) — SushiHangover, May 11 '19 at 02:38

score 3 · Answer 1 · edited Jul 17 '20 at 16:02

Reading:

# https://iterm2.com/python-api/session.html#iterm2.Session.async_get_variable
session_title = (await session.async_get_variable("autoName"))

Setting:

# https://iterm2.com/python-api/session.html#iterm2.Session.async_set_name
await session.async_set_name(session_title + "!")

Here is a more detailed example:

async def get_all_sessions(app:iterm2.app.App):
    for window in app.windows:
        window_title = (await window.async_get_variable("titleOverride"))
        print("window title: %s" % (window_title))
        # add window title suffix
        # await window.async_set_title(window_title+" ;)")
        # remove the added window title suffix
        # await window.async_set_title(window_title[0:-3])
        # print("window detailed: %s" % (window.pretty_str()))
        for tab in window.tabs:
            tab_title = (await tab.async_get_variable("titleOverride"))
            print("\t\ttab title: %s" % (tab_title))
            for session in tab.sessions:
                # https://iterm2.com/documentation-session-title.html
                # https://stackoverflow.com/questions/56069701/how-do-i-get-and-set-the-titles-of-the-window-tab-and-session-in-iterm-2-with
                # https://iterm2.com/python-api/session.html#iterm2.Session.async_get_variable
                session_title = (await session.async_get_variable("autoName"))
                print("\t\t\tsession title: %s" % (session_title))
                if session_title == "colabo-GIST":
                    print("\t\t\t: changing session name: %s" % (session_title))
                    # https://iterm2.com/python-api/session.html#iterm2.Session.async_set_name
                    await session.async_set_name(session_title + "!")
                # await session.async_inject(code)

How do I get and set the titles of the window, tab, and session in iTerm 2 (with the API)?

1 Answers1