Command-line essentials

Start with inspection#

harness-cli ls
harness-cli ls --json
harness-cli inspect
harness-cli list-surfaces
harness-cli daemon-stats --json

ls shows the session → tab → pane hierarchy. inspect gives context for one pane, including identity, directory, program, agent, and size. Run harness-cli with no arguments for command help.

Choose targets deliberately#

Named CLI target options accept a full ID, a label, a 1-based position within the caller’s context, or a unique ID fragment of at least four characters. An absent or ambiguous match fails rather than silently selecting an arbitrary pane.

Inside a pane, HARNESS_SURFACE, HARNESS_PANE, HARNESS_TAB, and HARNESS_SESSION provide caller context. Outside Harness, omitted targets usually follow the active app view. Automation should name targets explicitly when focus can change.

Create and run work#

harness-cli new-session --cwd ~/Code/my-project
harness-cli new-tab --cwd ~/Code/my-project
harness-cli run --label logs -- tail -f app.log
harness-cli run --split right --wait -- make test

The paths and commands above are examples; use your actual project. run prints the new surface ID, or structured creation data with --json. --wait returns the child command’s exit status. --keep-open leaves a completed run pane available for inspection.

Send keys and capture output#

harness-cli send-keys --surface "$HARNESS_SURFACE" --keys "ls -la Enter"
harness-cli capture-pane --surface "$HARNESS_SURFACE" --scrollback -S -100 -J

Key tokens such as Enter and C-c represent keystrokes, not literal strings. capture-pane can include scrollback and join soft-wrapped rows. Capture only the visible screen with --screen, or choose text, vt, or html with --format.

Handle exit statuses#

run --wait and successful pane.wait calls return the waited-for program’s own exit status. has-session preserves its special contract: 0 when present, 1 when missing. Do not treat every nonzero status as a transport failure.

Go beyond the essentials#

The full command reference covers pane movement and sizing, session groups, linked windows, copy mode, paste buffers, hooks, options, targets, the JSON API, and Lua. The source links below are pinned to the documented release. Use local help when running a newer binary.

2.0 workspace methods#

The workspace API adds attention, setup, closed-layout recovery, output search, and path search alongside the existing CLI. Ask your installed binary for schemas before adding arguments:

harness-cli api describe attention.list
harness-cli api describe setup.open
harness-cli api describe closed.restore
harness-cli api describe output.search
harness-cli api describe pane.search_paths

The caller’s host and pane context still matter. These methods need a compatible daemon; schema discovery alone does not prove that a remote server implements them.