# Koshi 0.6.0 — Session commands (/docs/v0.6/cli/sessions)



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](/docs/v0.6/using/attach-and-detach).

## Start [#start]

```bash
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`, on Linux and macOS; Windows
refuses it. That session serves the other users of this machine for its whole
life, whatever `koshi.kdl` says. See
[Sharing with other users](/docs/v0.6/using/other-users).

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

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

## `attach` [#attach]

```bash
koshi attach                 # pick from the running sessions
koshi attach S-amber-fox       # by name
koshi attach session-3f2a…   # by id
koshi attach --remote work S-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>)`:

```text
koshi attach
1) S-amber-fox session-3f2a…
2) S-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` [#detach]

```bash
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 S-amber-fox             # the same, by session name
koshi detach --all S-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, `<user id>/<session id>`, or a session name. A
terminal that has not come back since its session restarted is refused with
`client <id> is reconnecting`.

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` [#kill-session]

```bash
koshi kill-session                 # the only running session
koshi kill-session S-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.

koshi asks the session to end. If it quits, koshi also ends each process the
session left running, such as a `sleep 600 &` a pane shell started, and prints
how many. If it does not quit — it runs a koshi this one cannot talk to, or
does not answer — koshi ends the session process and every process under it.
koshi ends only processes that run as you, and never another koshi process.

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

| Exit code | Meaning                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `1`       | koshi cannot confirm that the process is the session; it names the process and the command that ends it |
| `3`       | Unknown session name or id                                                                              |
| `4`       | A session another user started did not answer                                                           |

## `list-sessions` [#list-sessions]

```bash
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, and an `owner` column: the user
id of another user of this machine whose session you can reach, else `-`. 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 whose connection failed, and a server that did not answer, are named
on standard error and their sessions are left out. A local session that does
not answer within 5 seconds is named the same way, and the command exits 4.

See [Discovery](/docs/v0.6/cli/discovery) for tabs, panes, and clients.

## Summary [#summary]

| Command                                    | Result                                                 |
| ------------------------------------------ | ------------------------------------------------------ |
| `koshi --headless`                         | Start a session with nothing attached and print its id |
| `koshi list-sessions`                      | List session ids and names                             |
| `koshi attach [NAME_OR_ID]`                | Attach this terminal to that session                   |
| `koshi detach [CLIENT_OR_SESSION]`         | Detach one terminal; the session keeps running         |
| `koshi detach --all [NAME_OR_ID]`          | Detach every terminal of that session                  |
| `koshi kill-session [NAME_OR_ID]`          | End that session, or the only running one              |
| `koshi attach --remote <SERVER> [SESSION]` | Attach to a session on another machine                 |