Skip to content

Control ButtonsCLI from a local agent

buttonsclictl lets local scripts and AI coding agents control a running ButtonsCLI window without screen scraping. It targets named tabs, sends input, reads recent output, and waits for terminal quiet.

Start from the app

Click Agent Inst. in the status bar. ButtonsCLI copies the current local helper instructions to your clipboard.

Paste those instructions into Codex CLI, Claude Code, Gemini CLI, or another local agent. This is the recommended handoff because it uses the installed helper and the current control token.

What the CLI can do

buttonsclictl can:

  • list open tabs
  • create a named tab
  • rename a tab
  • open several named tabs in a layout
  • read recent output from a tab
  • wait for specific text
  • wait until output stops changing
  • send text with or without Enter
  • run a command and wait for quiet
  • send control keys such as Ctrl+C
  • list and run saved presets

The app must already be running.

Use the installed helper

ButtonsCLI installs helper files under your home folder. On Windows, the help command usually looks like this:

"$HOME\.buttonscli\buttonsclictl.cmd" -h

Common commands:

"$HOME\.buttonscli\buttonsclictl.cmd" tabs
"$HOME\.buttonscli\buttonsclictl.cmd" read --tab active --lines 120
"$HOME\.buttonscli\buttonsclictl.cmd" run --tab active --text "git status"
"$HOME\.buttonscli\buttonsclictl.cmd" wait-for-quiet --tab active --quiet-ms 1500

Use the exact command copied by Agent Inst. when it differs from these examples.

Target tabs reliably

Most commands accept --tab.

You can target:

  • active
  • exact tab title
  • tab ID
  • PTY ID

Use unique tab names when an agent will control multiple terminals. Duplicate names make title-based selection unreliable and may be rejected.

Send larger payloads

For longer text, use payload sources that avoid shell quoting problems:

  • --stdin
  • --file
  • --base64

Use inline --text only for short commands.

If a remote shell mishandles large input, use slow typed delivery:

"$HOME\.buttonscli\buttonsclictl.cmd" send --tab active --delivery slow-typed --delay-ms 14 --file .\script.sh --enter

Understand the limits

The control surface is local-only. It reads a loopback URL and token from the app’s local control file.

Current limits:

  • ButtonsCLI must be open
  • control listens on 127.0.0.1
  • reads use recent captured output, not infinite terminal history
  • display tabs do not accept terminal input
  • automation does not make hidden paid features available
  • secret injection is not part of the first user-facing automation flow

Optional MCP helper

Some agents can connect through Model Context Protocol (MCP). If your agent supports MCP, use Settings under Advanced and Automation to copy the MCP setup block.

Prefer the direct CLI helper when the agent can run normal shell commands. It is easier to inspect and debug.