# Conventions (/docs/v0.1/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.

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

## 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 |

Capture them and reuse them:

```bash
pane=$(koshi new-pane --direction right)
koshi input --pane "$pane" "cargo watch -x test"
```

## 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 |
| `koshi --profile <NAME>` | Start from `profile/<NAME>.kdl`               |

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

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

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

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

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

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

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

  <Card title="Update" href="/docs/v0.1/cli/update" description="koshi update" />
</Cards>