Conventions

Every koshi subcommand works the same way from inside a session and from any other shell. What changes is how the target is chosen.

Choosing a target

• Inside koshi — an omitted target means the current session, tab, pane, or client.
• Outside koshi — give a target, unless exactly one session is running. Then koshi uses it. Zero or several running sessions fail rather than guess.

Targets are passed as --session, --tab, --pane, and --client, and take the ids that create and list commands print.

--remote <SERVER> runs one invocation against another machine instead of this one. Everything after that — how a session is named, how a missing name is resolved, what is refused — runs against that machine unchanged. See Remote commands.

One running session plus koshi new-tab puts a tab in that session. Two running sessions plus the same command fails, because koshi cannot choose safely.

Names and ids

A flag written NAME_OR_ID takes either the target's generated name or its printed id:

koshi kill-session amber-fox
koshi kill-session session-3f2a…

A value that reads as an id is always used as an id — it never falls back to a name lookup. A name that several targets share is refused, and the error lists every matching id. --pane and --client take ids only.

What create commands print

Ids print on stdout in creation order:

koshi new-tab
[TAB ID]: tab-<uuid>
[PANE ID]: pane-<uuid>

Each line is labelled, so take the id off the end of it before reusing it:

pane=$(koshi new-pane --direction right | awk '{print $NF}')
koshi input --pane "$pane" "cargo watch -x test"

Commands that create nothing print no id line.

Output format

List and inspect commands accept --format:

koshi list-panes --format table   # default, for reading
koshi list-panes --format json    # for scripts

Launching

The command map