Session commands

A session runs in its own process. These commands start one, join one, leave one, and end one. The concepts are on Attach and detach.

Start

koshi                        # start and attach this terminal
koshi --profile dev          # start from profile/dev.kdl
koshi --headless             # start with nothing attached
koshi --headless --allow-other-users   # the same, open to this machine's other users

--allow-other-users goes only with --headless. That session serves the other users of this machine for its whole life, whatever koshi.kdl says. See Sharing with other users.

--headless prints the session id and returns to the shell. Nothing is drawn.

koshi --headless
[SESSION ID]: session-3f2a…

attach

koshi attach                 # pick from the running sessions
koshi attach amber-fox       # by name
koshi attach session-3f2a…   # by id
koshi attach --remote work quiet-heron   # on another machine

Run outside koshi, attach opens that session in this terminal. Run inside a koshi pane, it moves this terminal to the named session instead.

With no argument, koshi lists this machine's sessions and the sessions on every saved server that answered, numbers them, and reads your answer. A session on a saved server carries (remote: <server>):

koshi attach
1) amber-fox session-3f2a…
2) quiet-heron session-91c4… (remote: work)
attach to which session? [1-2]

A listing of exactly one session, on this machine, is attached without asking. Every other listing asks, one session on a saved server included, whose prompt reads attach to which session? [1].

detach

koshi detach                       # inside a pane: this terminal
koshi detach client-0e5a…          # a client id
koshi detach session-3f2a…         # that session's client, by id
koshi detach amber-fox             # the same, by session name
koshi detach --all amber-fox       # every terminal of that session

Detaching leaves the session running with its panes untouched. Bare koshi detach works only inside a koshi pane. Outside one, name the target: a client id, a session id, or a session name.

A session left with no terminal keeps running, unless auto-close-session is #true in the koshi.kdl the session read when it started.

kill-session

koshi kill-session                 # the only running session
koshi kill-session amber-fox       # by name
koshi kill-session session-3f2a…   # by id

Ends the session and everything in it, whatever is attached. An id goes straight to that session with no lookup. With no argument it works only when exactly one session is running.

kill-session skips the wait that auto-close-session gives programs to stop.

list-sessions

koshi list-sessions
koshi list-sessions --format json

Prints session ids and names, with a server column: local for a session on this machine, else the saved server it runs on. A bare koshi list-sessions sweeps every saved server and appends what answered; koshi list-sessions --remote <server> lists that one server's sessions alone.

A server that refused the saved secret, and a server that did not answer, are named on standard error and their sessions are left out.

See Discovery for tabs, panes, and clients.

Summary