libtmux Documentation Release 0.8.3 Tony Narlock Aug 16, 2020 CONTENTS 1 install 3 2 open a tmux session 5 3 pilot your tmux session via python7 4 Donations 9 4.1 Quickstart................................................9 4.2 About................................................... 13 4.3 Properties................................................. 15 4.4 Traversal................................................. 18 4.5 Servers.................................................. 19 4.6 Sessions................................................. 24 4.7 Windows................................................. 28 4.8 Panes................................................... 33 4.9 API Reference.............................................. 36 4.10 Glossary................................................. 58 4.11 Developing and Testing......................................... 59 4.12 History.................................................. 62 Python Module Index 67 Index 69 i ii libtmux Documentation, Release 0.8.3 libtmux is the tool behind tmuxp, a tmux workspace manager in python. it builds upon tmux’s target and formats to create an object mapping to traverse, inspect and interact with live tmux sessions. view the documentation homepage, API information and architectural details. CONTENTS 1 libtmux Documentation, Release 0.8.3 2 CONTENTS CHAPTER ONE INSTALL $[sudo] pip install libtmux 3 libtmux Documentation, Release 0.8.3 4 Chapter 1. install CHAPTER TWO OPEN A TMUX SESSION session name foo, window name bar $ tmux new-session -s foo -n bar 5 libtmux Documentation, Release 0.8.3 6 Chapter 2. open a tmux session CHAPTER THREE PILOT YOUR TMUX SESSION VIA PYTHON $ python # or for nice autocomplete and syntax highlighting $ pip install ptpython $ ptpython connect to a live tmux session: >>> import libtmux >>> server= libtmux.Server() >>> server <libtmux.server.Server object at 0x7fbd622c1dd0> list sessions: >>> server.list_sessions() [Session($3 foo), Session($1 libtmux)] find session: >>> server.get_by_id('$3') Session($3 foo) find session by dict lookup: >>> server.find_where({"session_name":"foo"}) Session($3 foo) assign session to session: >>> session= server.find_where({"session_name":"foo"}) play with session: >>> session.new_window(attach=False, window_name="ha in the bg") Window(@8 2:ha in the bg, Session($3 foo)) >>> session.kill_window("ha in") create new window in the background (don’t switch to it): >>> w= session.new_window(attach=False, window_name="ha in the bg") Window(@11 3:ha in the bg, Session($3 foo)) kill window object directly: 7 libtmux Documentation, Release 0.8.3 >>> w.kill_window() grab remaining tmux window: >>> window= session.attached_window >>> window.split_window(attach=False) Pane(%23 Window(@10 1:bar, Session($3 foo))) rename window: >>> window.rename_window('libtmuxower') Window(@10 1:libtmuxower, Session($3 foo)) create panes by splitting window: >>> pane= window.split_window() >>> pane= window.split_window(attach=False) >>> pane.select_pane() >>> window= session.new_window(attach=False, window_name="test") >>> pane= window.split_window(attach=False) send key strokes to panes: >>> pane.send_keys('echo hey send now') >>> pane.send_keys('echo hey', enter=False) >>> pane.enter() grab the output of pane: >>> pane.clear() # clear the pane >>> pane.send_keys('cowsay hello') >>> print('\n'.join(pane.cmd('capture-pane','-p').stdout)) sh-3.2$ cowsay 'hello' _______ < hello > ------- \ ^__^ \ (oo)\_______ (__)\ )\/\ ||----w | || || powerful traversal features: >>> pane.window Window(@10 1:libtmuxower, Session($3 foo)) >>> pane.window.session Session($3 foo) 8 Chapter 3. pilot your tmux session via python CHAPTER FOUR DONATIONS Your donations fund development of new features, testing and support. Your money will go directly to maintenance and development of the project. If you are an individual, feel free to give whatever feels right for the value you get out of the project. See donation options at https://git-pull.com/support.html. Explore: 4.1 Quickstart libtmux allows for developers and system administrators to control live tmux sessions using python code. In this example, we will launch a tmux session and control the windows from inside a live tmux session. 4.1.1 Requirements • tmux • pip - for this handbook’s examples 4.1.2 Installation Next, ensure libtmux is installed: $[sudo] pip install libtmux 4.1.3 Start a tmux session Now, let’s open a tmux session. $ tmux new-session -n bar -s foo This tutorial will be using the session and window name in the example. Window name -n: bar Session name -s: foo 9 libtmux Documentation, Release 0.8.3 4.1.4 Control tmux via python See also: API Reference $ python For commandline completion, you can also use ptpython. $[sudo] pip install ptpython $ ptpython First, we can grab a Server. >>> import libtmux >>> server= libtmux.Server() >>> server <libtmux.server.Server object at 0x7fbd622c1dd0> Note: You can specify a socket_name, socket_path and config_file in your server object. libtmux. Server(socket_name='mysocket') is equivalent to $ tmux -L mysocket. server is now a living object bound to the tmux server’s Sessions, Windows and Panes. 4.1.5 Find your Session If you have multiple tmux sessions open, you can see that all of the methods in Server are available. We can list sessions with Server.list_sessions(): >>> server.list_sessions() [Session($3 foo), Session($1 libtmux)] This returns a list of Session objects you can grab. We can find our current session with: >>> server.list_sessions()[0] However, this isn’t guaranteed, libtmux works against current tmux information, the session’s name could be changed, or another tmux session may be created, so Server.get_by_id() and Server.find_where() exists as a lookup. 4.1.6 Get session by ID tmux sessions use the $[0-9] convention as a way to identify sessions. $3 is whatever the ID list_sessions() returned above. >>> server.get_by_id('$3') Session($3 foo) You may session = server.get_by_id('$<yourId>') to use the session object. 10 Chapter 4. Donations libtmux Documentation, Release 0.8.3 4.1.7 Get session by name / other properties >>> server.find_where({"session_name":"foo"}) Session($3 foo) With find_where, pass in a dict and return the first object found. In this case, a Server holds a collection of child Session. Session and Window both utilize find_where to sift through Windows and Panes, respectively. So you may now use: >>> session= server.find_where({"session_name":"foo"}) to give us a session object to play with. 4.1.8 Playing with our tmux session We now have access to session from above with all of the methods available in Session. Let’s make a Session.new_window(), in the background: >>> session.new_window(attach=False, window_name="ha in the bg") Window(@8 2:ha in the bg, Session($3 foo)) So a few things: 1. attach=False meant to create a new window, but not to switch to it. It is the same as $ tmux new-window -d. 2. window_name may be specified. 3. Returns the Window object created. Note: Use the API reference API Reference for more commands. Let’s delete that window (Session.kill_window()). Method 1: Use passthrough to tmux’s target system. >>> session.kill_window("ha in") The window in the bg dissappeared. This was the equivalent of $ tmux kill-window -t'ha in' Internally, tmux uses target. Its specific behavior depends on what the target is, view the tmux manpage for more information: This section contains a list of the commands supported by tmux. Most commands accept the optional-t argument with one of target-client, target-session, target-window, or target-pane. In this case, you can also go back in time and recreate the window again. The CLI should have history, so navigate up with the arrow key. >>> session.new_window(attach=False, window_name="ha in the bg") Window(@11 3:ha in the bg, Session($3 foo)) Try to kill the window by the matching id @[0-9999]. 4.1. Quickstart 11 libtmux Documentation, Release 0.8.3 >>> session.new_window(attach=False, window_name="ha in the bg") Window(@12 3:ha in the bg, Session($3 foo)) In addition, you could also .kill_window direction from the Window object: >>> window= session.new_window(attach=False, window_name="check this out") And kill: >>> window.kill_window() Use Session.list_windows() and Session.find_where() to list and sort through active Window’s. 4.1.9 Manipulating windows Now that we know how to create windows, let’s use one. Let’s use Session.attached_window() to grab our current window. >>> window= session.attached_window() window now has access to all of the objects inside of Window. Let’s create a pane, Window.split_window(): >>> window.split_window(attach=False) Pane(%23 Window(@10 1:bar, Session($3 foo))) Powered up. Let’s have a break down: 1. window = session.attached_window() gave us the Window of the current attached to window. 2. attach=False assures the cursor didn’t switch to the newly created pane. 3. Returned the created Pane. Also, since you are aware of this power, let’s commemorate the experience: >>> window.rename_window('libtmuxower') Window(@10 1:libtmuxower, Session($3 foo)) You should have noticed Window.rename_window() renamed the window. 4.1.10 Moving cursor across windows and panes You have two ways you can move your cursor to new sessions, windows and panes. For one, arguments such as attach=False can be omittted. >>> pane= window.split_window() This gives you the Pane along with moving the cursor to a new window. You can also use the .select_* available on the object, in this case the pane has Pane.select_pane(). >>> pane= window.split_window(attach=False)