Automation, API & events

Run work and wait for the result#

Use run for commands that belong in a visible terminal pane. --wait propagates the child’s status to your script. A run pane closes after completion unless you use --keep-open.

harness-cli run --split right --wait -- make test
status=$?
printf "Test command exited with %s\n" "$status"
exit "$status"

This example is a script: its final exit terminates the shell that executes it. Do not paste that final line into a working interactive shell unless you intend to close it.

Discover the JSON API#

The API describes itself. list and describe print method schemas without requiring a running daemon. Check a method’s schema before constructing arguments.

harness-cli api list
harness-cli api describe pane.capture
harness-cli api call server.version --args '{}'
harness-cli api call session.list --args '{}'

Calls are planned and validated before mutation. pane.view combines common pane details in one response; pane.capture, pane.write, pane.send_key, pane.wait, session.create, and tab.create support more involved workflows.

Avoid focus-dependent automation#

Use IDs from list or creation output and explicit targets when another client may change the active tab. A missing or ambiguous target exits 3; an unreachable daemon exits 4. The same target-resolution rules are used by the CLI, JSON API, and Lua.

Bindable commands can also be called as API methods. This example splits the calling or active pane, so run it only after confirming that context:

harness-cli api call split-window --args '{"args":"-h"}'

Subscribe instead of polling#

harness-cli events --follow --json
# Include server-wide events as well:
harness-cli events --follow --json --all

Without --follow, events returns a one-shot snapshot. The live JSON stream uses newline-delimited objects with type and payload. When HARNESS_SESSION is present, the default scope is that session; --session pins one explicitly.

Event names include pane.created, pane.closed, terminal.child_exited, terminal.program_status, and agent.state. Server events such as client.connected need --all. Consumers should tolerate unknown event names and additional payload fields rather than failing on an additive change.

Know the execution boundary#

A method that requires the native GUI, such as an overlay, may not work from a headless context. Report and handle the returned error rather than treating every bindable command as a portable server operation.

--host targets a remote daemon through SSH. HARNESS_SERVER selects the socket for local CLI/API calls when --host is absent. The API does not create a separate public network service or bypass the daemon’s same-user security boundary.

Workspace automation in 2.0#

harness-cli api call attention.list --args '{}'
harness-cli api call output.search --args '{"query":"error","case_sensitive":false}'

Use api describe for exact input and result schemas. Opening a setup or restoring a closed entry creates processes. Importing a setup does not execute it, and reattaching to an existing setup does not rerun startup commands.