liney-cli

name

liney-cli

description

Use the Liney CLI (`liney`) to inspect or control a running Liney terminal workspace and the agent sessions it hosts. Liney runs several coding agents in parallel, each in its own pane/tab/worktree, so reach for this whenever the user wants to act on a pane other than the current one — check on, coordinate, read from, or send text/keys to another pane, tab, worktree, or sibling agent. Covers framings that never say "liney": "what is the agent in my other window doing", "are my side-by-side agents still working or waiting?", "tell the agent in my left split to rerun the tests", "read the build pane's output", "which of my agents is blocked?". Not for ordinary editing or building inside the Liney source repo, and not for questions about Liney's settings or keybindings — only when the task is to actually drive panes in the live app.

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).