Driving MiniCon from a script
MiniCon exposes the same surface to a script that a person uses through the window. There is no separate automation mode: the control CLI drives the real UI, and what you read back is what the window is actually showing.
This exists because a terminal an agent can drive has to be observable, not just controllable. Sending a key is easy; knowing what happened next is the hard half.
Opening an endpoint
Start MiniCon with a control endpoint, then talk to it with the same executable:
minicon --control pipe:\\.\pipe\my-session
minicon cli --control pipe:\\.\pipe\my-session list-tabs
The endpoint is a named pipe on Windows and a Unix socket elsewhere. The Windows form
needs the full local namespace — pipe:\\.\pipe\NAME. A bare name is refused
rather than silently misinterpreted.
Every command prints JSON on stdout and exits nonzero on failure, so a script can branch on the exit status and parse the body without scraping prose.
Reading state
| Command | Answers |
|---|---|
list-tabs | every tab, its @ID, title, parent, and whether its child is alive |
ui-snapshot | focus, IME state, input contents, pending work, control geometry |
capture-pane | the pane as text |
screenshot-pane | the pane as a PNG |
perf-stats | frame and throughput counters |
list-tabs reporting "child_alive": false with an exit code is
how a script learns a command finished — without polling the screen for a prompt.
Waiting instead of sleeping
minicon cli --control ENDPOINT wait-text --timeout-ms 20000 "BUILD OK"
minicon cli --control ENDPOINT wait-tab-exit --target @2 --timeout-ms 60000
Both block until the condition holds or the timeout expires, and report which happened.
A fixed sleep is either too short and flaky or too long and slow; these are
neither.
Sending input
| Command | Use |
|---|---|
send-text | type text into a terminal |
send-paste | paste, with bracketed-paste handling |
send-keys | named keys — Enter, Escape, Tab, Up, F1, Ctrl+C |
send-ui-keys | follows current UI focus rather than a terminal |
send-ui-ime | drive an IME preedit and commit |
send-mouse | pointer events in terminal cells |
send-wheel | scroll; positive notches scroll up |
send-keys always addresses a terminal; send-ui-keys addresses
whatever has focus, which is how you reach the tab column and the input line.
Managing tabs
minicon cli --control ENDPOINT new-tab [--parent TAB]
minicon cli --control ENDPOINT select-tab --target @2
minicon cli --control ENDPOINT close-tab --target @2
minicon cli --control ENDPOINT resize-window --width 1000 --height 700
minicon cli --control ENDPOINT close-window
Tabs form a tree. Closing a parent promotes its children rather than taking them with
it. @ID values are stable for the life of a tab, so a script can hold one
across many commands without re-reading the list.
Running one command instead of a shell
-e replaces the default shell. Everything after it is passed through
verbatim, so it has to come last:
minicon -e cmd.exe /k my-build.bat
Combined with wait-tab-exit, this makes MiniCon a way to run something in a
real terminal — with a real PTY, real VT handling, and a screen you can screenshot — and
then collect the result.
Checking what you are talking to
minicon --statusReports the build, the PTY backend this machine selected, the font face the system resolved to and its measured cell width, and where MiniCon writes when something fails. It opens no window, so a script can call it before deciding whether to start a session at all.
Discovering the surface
minicon cli list-commandsPrints the command list with no endpoint and no running window, which is what lets a script check what a given build supports before depending on it.