everettjf/liney/liney-cli

Liney CLI

Use liney only when the task is to inspect or control the running Liney GUI app: list/read panes, check sibling agents, send text/keys, or report your own status. Do not use it merely because the current shell is inside the Liney repo.

Auth

Most of the time you need to do nothing. When Settings → URL Scheme is enabled, Liney injects LINEY_CONTROL_TOKEN into every pane's environment, so an agent running in a Liney pane can call the mutating commands (open, split, send-keys) with no setup.

• No token at all: session list, read, agents (read-only inspection)

and notify, status (self-reports). These always work.

• **Token (auto-injected, or export LINEY_CONTROL_TOKEN=<token> if you run

from outside a Liney pane):** open, split, send-keys.

Identify a pane before acting

Always resolve a concrete pane UUID before read or send-keys.

liney session list --json | jq -r '.[].pane'   # all panes (id, cwd, branch, ports, status)
liney agents --json       | jq -r '.[].pane'   # only panes with a detected/reported agent

liney agents is the right starting point for "which agents are blocked / working / done?"; liney session list is the full pane inventory including plain shells.

If your own session was launched from a Liney pane, the focused pane is often you. Treat focused pane IDs as something to identify and avoid unless you mean to operate on yourself.

self_pane="$(liney agents --json | jq -r '.[] | select(.focused) | .pane')"

Read another pane

liney read --pane "$pane" --last 80 --json | jq -r '.text'
liney read --pane "$pane" --scrollback --json | jq -r '.text'     # include history
liney read --pane "$pane" --last 200 --wait-stable --json | jq -r '.text'

--wait-stable re-reads until the screen stops changing — use it when an agent's TUI may still be streaming a response so you don't read a half-painted frame.

Drive another pane

liney send-keys "$pane" 'npm test\n'          # text, trailing \n submits
liney send-keys "$pane" $'\x03'               # Ctrl-C
liney open ~/proj --worktree ~/proj/.wt/x     # open a repo / switch worktree
liney split --axis vertical --pane "$pane"    # split a pane

Use this only for a pane you have positively identified. If $pane is your own pane, the keys land in your current session.

Report your own status (no token)

When you are the agent in a Liney pane, tell Liney how you're doing so the user sees it in the dynamic island and liney agents:

liney status waiting --title "Approve running the migration?"
liney status done
liney status error --title "build failed"

A typical "check on a blocked agent" loop

self_pane="$(liney agents --json | jq -r '.[] | select(.focused) | .pane')"
pane="$(liney agents --json | jq -r --arg me "$self_pane" '
  .[] | select(.status == "waiting" and .pane != $me) | .pane' | head -n1)"
test -n "$pane" && liney read --pane "$pane" --last 120 --wait-stable --json | jq -r '.text'

Parsing JSON output

• session list --json → array of { workspace, workspaceName, pane, cwd, branch, ports, status }.
• agents --json → array of { workspace, workspaceName, pane, type, name, status, reported, cwd, branch, focused }.
• status is running | waiting | done | error.
• reported is true when status came from a liney status self-report,

false when it was passively detected from the pane's process tree.

• read --json → { ok, text, lineCount }; the terminal text is .text.

When JSON is stored in a shell variable, use printf '%s\n' "$json" | jq ..., not echo "$json" | jq — zsh can turn JSON escape sequences such as  back into raw control characters.

Installing the CLI shim

The Liney app binary is itself the CLI:

sudo ln -sf /Applications/Liney.app/Contents/MacOS/Liney /usr/local/bin/liney

Exit codes

0 ok · 64 usage · 69 Liney not running · 74 I/O error · 77 auth required (missing/invalid token).