Skip to main content
tty7 is a thin, non-interactive client of the tty7 server. Every verb runs and exits; --json makes the output machine-readable. The GUI does not have to be running — the server is what owns the panes. It ships inside every installer and is put on PATH at launch, so it works from any terminal on the machine. Installation →

​
Start with doctor

One table that answers everything you need before doing anything else: whether a server is reachable, whether its wire dialect matches this binary, and whether TTY7_CONFIG_DIR / TTY7_WS / TTY7_PANE are set — that is, whether you are running inside a tty7 pane. Being inside a pane matters because the address-taking verbs (split, send, capture, procs, wait, pane close) default to $TTY7_PANE, and run --keep files its pane into $TTY7_WS. Outside one you must name a target, and the error says so rather than guessing.

​
Addresses

Re-resolve @N immediately before using it. Pane and workspace ids are safe to remember.

​
Two ways to run something

​
Blocking, with a real exit code

The closest thing to running the command yourself — the difference is that it gets a real PTY (so colour, progress bars, and TUIs behave), and that you can watch it happen in the window.
Everything after -- belongs to the child: tty7 run -- cargo test --keep passes --keep to cargo, not to tty7.

​
Non-blocking: a pane you talk to over time

This is the one worth reaching for. Get a pane, give it work, come back.
If you are not inside a tty7 pane there is nothing to split, so make your own place to work:

​
Reading a pane

capture returns what the server stored. Without --plain that is the raw bytes, escapes and all. With --plain those bytes are replayed through a real terminal grid and you get the text that produced — which is not the same as stripping escapes yourself:
  • A line the shell wrapped at the pane width comes back as one line
  • A progress bar that rewrote itself with \r reads as its final value
  • Cursor addressing puts text where the program put it, so a TUI’s screen lands where it was drawn
Use --plain whenever a human would want to read the output.
A screen is a rectangle. Whatever scrolled off the top is gone, and an exit code was never on it. When you want the answer rather than the view, have the shell write it somewhere clean:

​
Knowing when something finished

The process tree inside the pane, indented by depth, with * on the foreground process — plus the ports those processes are listening on. When the only entry left is the depth-0 shell, the command is done. That is far more reliable than grepping the screen for a sentinel that can wrap or echo twice. For agents specifically, use tty7 wait instead of polling.

​
Looking around

--json on any of them, -q to suppress success output (errors still print).

​
Remote machines

-m routes over a link the local server already holds. It will not dial a fresh connection — connect from the GUI first. Remote workspaces →

Full command reference

Every verb, flag, and JSON shape.