# Conventions (/docs/v0.4/cli)



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 [#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](/docs/v0.4/cli/remote).

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 [#names-and-ids]

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

```bash
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 [#what-create-commands-print]

| Command            | Prints                      |
| ------------------ | --------------------------- |
| `koshi new-pane`   | one pane id                 |
| `koshi run`        | one pane id                 |
| `koshi new-tab`    | its tab id and root pane id |
| `koshi --headless` | its session id              |

Ids print on stdout in creation order:

```text
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:

```bash
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 [#output-format]

List and inspect commands accept `--format`:

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

## Launching [#launching]

| Command                                | Result                                                                   |
| -------------------------------------- | ------------------------------------------------------------------------ |
| `koshi`                                | Start one session with one tab and shell pane, attached to this terminal |
| `koshi --profile <NAME>`               | Start from `profile/<NAME>.kdl`                                          |
| `koshi --headless`                     | Start a session with nothing attached, print its id, and return          |
| `koshi --headless --allow-other-users` | The same, and let this machine's other users reach the session           |

## The command map [#the-command-map]

<Cards>
  <Card title="Sessions" href="/docs/v0.4/cli/sessions" description="attach, detach, kill-session, --headless" />

  <Card title="Panes" href="/docs/v0.4/cli/panes" description="new-pane, run, close-pane, resize-pane, focus-pane, input" />

  <Card title="Tabs" href="/docs/v0.4/cli/tabs" description="new-tab, close-tab, next, previous, focus, move" />

  <Card title="Discovery" href="/docs/v0.4/cli/discovery" description="list-sessions, list-tabs, list-panes, list-clients, inspect" />

  <Card title="Input lock" href="/docs/v0.4/cli/input-lock" description="lock, unlock, toggle-lock" />

  <Card title="Keys and actions" href="/docs/v0.4/cli/keys-and-actions" description="keys list, describe, conflicts, validate; actions list, explain" />

  <Card title="Remote" href="/docs/v0.4/cli/remote" description="share grant, revoke, list; remote new, edit, list, forget, set-secret; --remote" />

  <Card title="Config" href="/docs/v0.4/cli/config" description="config path, explain, check, migrate" />

  <Card title="Doctor" href="/docs/v0.4/cli/doctor" description="koshi doctor — one row per installation check" />

  <Card title="Debug" href="/docs/v0.4/cli/debug" description="debug dump-state, debug dump-layout, debug events" />

  <Card title="Update" href="/docs/v0.4/cli/update" description="koshi update, koshi version, koshi server-version" />
</Cards>