Embedded CLI

How It Works

Zentty injects ZENTTY_CLI_BIN, the instance socket, pane IDs, worklane IDs, and a pane token into each terminal session. User-facing commands send pane or discovery requests to the running app over that socket. Most commands must run inside Zentty unless you explicitly export a selected pane context.

Discovery commands use a read-only IPC path and can return JSON. Pane commands use pane IPC and require the pane token when called from outside the original pane.

CLI Path

Inside every Zentty pane, ZENTTY_CLI_BIN points to the bundled binary and the pane environment supplies the socket, ids, and token needed for local IPC. Outside Zentty, create your own alias or symlink if you want convenience, then export pane context with zentty select pane --shell.

Output And Exit Codes

Command names are intended to be stable. If a command is replaced, the old spelling should remain as an alias for at least one release cycle when practical.

JSON Schemas

JSON output is shaped for scripts: opaque ids stay opaque, indexes are user-facing, and agent status is nested under the pane when available.

zentty list panes --json
{
  "windowId": "win_...",
  "worklaneId": "lane_...",
  "panes": [
    {
      "id": "pane_...",
      "index": 1,
      "column": 1,
      "workingDirectory": "/Users/you/project",
      "title": "Claude",
      "agent": {
        "tool": "claude",
        "phase": "needs-input",
        "interaction": "approval"
      }
    }
  ]
}

Command Groups

Targeting

Pane commands accept selectors for window ID, worklane ID, pane ID, pane index, and pane token. If you omit selectors, commands default to the current pane and worklane when the environment provides enough context.

zentty pane focus 2
zentty pane focus right
zentty split down --golden
zentty layout thirds
zentty worklane color teal
zentty list --json

Out-Of-Pane Control

To control a pane from another shell, resolve it with zentty select pane and request shell exports. Include the control token only when you need to send pane operations from outside the original pane.

Tokens are scoped to the pane and current Zentty instance. They should be treated as local secrets: do not paste them into shared shells, remote sessions, logs, or issue reports. Close the pane to revoke the token.

zentty select pane --pane-index 1 --shell --include-control-token
export ZENTTY_INSTANCE_SOCKET='...'
export ZENTTY_WINDOW_ID='...'
export ZENTTY_WORKLANE_ID='...'
export ZENTTY_PANE_ID='...'
export ZENTTY_PANE_TOKEN='...'

Internal Helpers

These commands are hidden from normal help because generated hooks call them, but documenting the I/O contract makes custom integrations easier.

Recipe Book

# Focus the pane currently running Claude
zentty list panes --json | jq -r '.panes[] | select(.agent.tool=="claude") | .id' | head -1 | xargs zentty pane focus

# Apply thirds to the current worklane
zentty layout thirds

# Color the current worklane by repo state
zentty worklane color amber

# Export a trusted control context
zentty select pane --pane-index 1 --shell --include-control-token

# List idle agent panes
zentty list panes --json | jq '.panes[] | select(.agent.phase=="idle")'

# Open a visible right split for a review pane
zentty split right --golden

# Reset layout after a focused debugging session
zentty layout reset

# Forward a custom needs-input event
printf '%s
' '{"version":1,"event":"agent.needs-input"}' | zentty ipc agent-event

Hook Install Paths

Manual install commands write only the relevant tool's local hook config and can be undone with the matching uninstall command.

Automation Patterns