# Koshi 0.6.0 — Pane commands (/docs/v0.6/cli/panes) Inside koshi, omitted targets use the current session, tab, pane, or client. Outside koshi, pass a target unless exactly one running session can be chosen. Without `--pane`, `close-pane`, `resize-pane`, `scroll-pane`, and `input` act on the pane the command runs in, or, outside koshi, on the pane that takes the client's keys: its focused floating pane, else its focused pane in its tab. These verbs take `--remote ` to act on a session on another machine. See [Remote commands](/docs/v0.6/cli/remote). ## `new-pane` [#new-pane] Open a shell pane: ```bash koshi new-pane koshi new-pane --direction left koshi new-pane --stacked koshi new-pane --floating ``` Main flags: | Flag | Meaning | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `--direction right\|down\|left\|up` | Open the new pane beside its target | | `--stacked` | Add it to the target's stack | | `--pane ` | Split this pane | | `--tab ` | Create inside this tab | | `--session ` | Choose the session | | `--client ` | The client that shows and focuses the new pane. Outside koshi with no `--pane` or `--tab`, the new pane splits this client's focused pane | | `--floating` | Open the pane floating above the tiled panes; see [Floating panes](#floating-panes) | `--direction` and `--stacked` are alternatives. The command prints one pane id. The new pane starts in the current working directory of the pane it splits from, with the environment the session process started with plus koshi's own variables. Outside koshi with no `--pane`, `--tab`, or `--client`, the new pane splits the focused pane of the session's only attached client. With several clients attached, the command fails with `several clients are attached; name the target client`. Inside a floating pane, `new-pane` without `--pane` is refused; use `--floating`, or dock the pane first. ## `run` [#run] Open a pane running one command: ```bash koshi run -- htop koshi run --direction down -- cargo watch -x test ``` Placement flags match `new-pane`, `--floating` included. Everything after `--` is the command and its arguments. The command prints one pane id. ## `close-pane` [#close-pane] ```bash koshi close-pane koshi close-pane --pane koshi close-pane --pane --force ``` Closing the last pane closes its tab. `--force` kills the pane's program at once instead of asking it to stop first. ## `resize-pane` [#resize-pane] ```bash koshi resize-pane --direction right koshi resize-pane --direction left --size 4 --pane koshi resize-pane --direction right --size -2 ``` Directions are `right`, `down`, `left`, and `up`. A positive size grows toward that direction; a negative size shrinks from that side. The border moves up to `--size` cells, as far as minimum sizes allow; a border that cannot move one cell is refused and nothing changes. On a floating pane, `--client` names the client whose view keeps the opposite edge in place, and the pane grows only up to that client's pane area edge. With several clients attached and no `--client`, the resize is refused. ## `focus-pane` [#focus-pane] ```bash koshi focus-pane --pane koshi focus-pane --pane --client koshi focus-pane --next-floating koshi focus-pane --previous-floating ``` Focus belongs to a client. `--client` chooses which attached terminal moves. `--pane` also takes a floating pane, minimized or not: it shows above the client's other floating panes and takes its keys. `--next-floating` and `--previous-floating` show and focus the next or previous floating pane, in the order the panes became floating, wrapping at the ends. ## `move-pane` [#move-pane] Swap a tiled pane with its visible neighbor immediately, without a preview or confirmation: ```bash koshi move-pane --direction right koshi move-pane --direction left --pane ``` | Flag | Meaning | | ----------------------------------- | --------------------------------------------- | | `--direction right\|down\|left\|up` | Choose the visible neighbor in this direction | | `--pane ` | Pane to move; defaults to the focused pane | To move a floating pane on one client's screen, give `--x` and `--y` instead; see [Floating panes](#floating-panes). ## `place-pane` [#place-pane] Insert a pane into a tab's tiled layout, on one side of the whole tab or into the stack of another pane. A floating pane docks. ```bash koshi place-pane --pane --tab --direction right koshi place-pane --pane --stack-onto ``` | Flag | Meaning | | ----------------------------------- | ------------------------------------------------------------------------------------------------------ | | `--pane ` | Pane to place; defaults to the pane this command runs in, else the focused pane | | `--tab ` | Destination tab, by id or name | | `--direction right\|down\|left\|up` | Side of the destination tab where the pane lands | | `--stack-onto ` | Tiled pane whose stack the pane joins as the open member; a pane in no stack forms a new stack with it | | `--client ` | Client whose view sizes the destination layout | ## `scroll-pane` [#scroll-pane] ```bash koshi scroll-pane --lines 10 koshi scroll-pane --lines -10 --pane koshi scroll-pane --lines 5 --client ``` Scrolls one client's view of a pane. A positive count moves toward history; a negative count moves toward the newest output. `--pane` defaults to the client's focused pane, and `--client` defaults to the issuing client. ## `toggle-pane-fullscreen` [#toggle-pane-fullscreen] ```bash koshi toggle-pane-fullscreen koshi toggle-pane-fullscreen --client ``` Fill the current tab with its focused pane, or restore the prior layout. The fullscreen view belongs to one client; `--client` names which one. A floating pane cannot go fullscreen; inside one, or outside koshi while one takes the client's keys, the command is refused. ## `input` [#input] ```bash koshi input --pane "cargo test" koshi input --pane --no-enter "git status" ``` Text is followed by Enter unless `--no-enter` is present. ## Floating panes [#floating-panes] A floating pane sits above the tiled panes and belongs to no tab. A session holds at most 12. Where it sits, whether it is pinned, and whether it is minimized belong to each client; the pane and its program belong to the session. ### Open one [#open-one] ```bash koshi new-pane --floating koshi run --floating --cols 80 --rows 60% --x 4 --y 2 -- htop ``` | Flag | Meaning | | ------------------ | ---------------------------------------------------------------------------------------- | | `--floating` | Open the pane floating. Refused with `--direction`, `--stacked`, `--pane`, and `--tab` | | `--cols ` | Width: columns (`80`) or a percent of the pane area (`60%`); needs `--rows`. Default 60% | | `--rows ` | Height: rows (`20`) or a percent (`60%`); needs `--cols`. Default 60% | | `--x ` | Column of the top-left cell, from the left edge of the pane area; needs `--y` | | `--y ` | Row of the top-left cell, from the top edge of the pane area; needs `--x` | | `--pinned` | Pin the pane on the client that shows it | Each axis is cut to 90% of the smallest pane area of the attached clients: `--cols 100% --rows 100%` on an `80x22` pane area gives `72x19`. The client `--client` names, else the issuing client, else the session's only attached client, shows the pane and gives it its keys. Every other client holds it minimized. A client whose pane area is smaller than `5x6`, or that shows `Terminal too small — enlarge window`, cannot draw floating panes and holds it minimized too. ### Float and dock [#float-and-dock] ```bash koshi undock-pane koshi undock-pane --pane --x 10 --y 2 koshi dock-pane koshi dock-pane --pane --tab --direction down koshi dock-pane --pane --stack-onto ``` `undock-pane` floats a tiled or stacked pane where the client draws it, keeping its top-left cell and size (each axis cut to 90% as above). `--x` and `--y` move its top-left cell. The other panes of its tab fill the space. The last tiled pane of the session's only tab cannot be undocked. `dock-pane` puts a floating pane into a tab's tiled layout, on the side `--direction` names (`right` by default), or into the stack of the pane `--stack-onto` names. Without `--tab`, it uses the tab the `--client` client views, else the tab of the tiled pane the command runs in, else the tab the issuing client or the session's only attached client views, else the session's only tab. A tab with no room refuses with `tab has no room for another pane`. | Flag | `undock-pane` | `dock-pane` | | ------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------- | | `--pane ` | Pane to float; defaults to the pane this command runs in, else the focused pane | Floating pane to dock; same default | | `--tab ` | — | Destination tab | | `--direction` | — | Side of the destination tab; default `right` | | `--stack-onto ` | — | Tiled pane whose stack the pane joins | | `--x`, `--y` | Top-left cell | — | | `--client ` | Client that shows and focuses the floating pane | Client that moves to the destination tab | ### Move, pin, minimize, restore [#move-pin-minimize-restore] ```bash koshi move-pane --pane --x 20 --y 3 koshi pin-pane koshi unpin-pane --pane koshi minimize-pane koshi minimize-pane --all koshi restore-pane --pane koshi restore-pane --all ``` These change one client's screen; `--client` names which, defaulting to the issuing client, else the session's only attached one. Without `--pane`, they act on the pane they run in, or from outside koshi on the client's focused floating pane. * `move-pane --x --y` moves the pane's top-left cell. `--pane` is required. A pinned pane is refused with ` is pinned; unpin it to move it`. * `pin-pane` keeps the pane at its top-left cell: that client's moves and left or top edge resizes are refused. `unpin-pane` releases it; it stays where it is. * `minimize-pane` hides the pane on that client; its program keeps running. `--all` minimizes every floating pane the client shows. * `restore-pane` shows a minimized pane again. `--all` restores every floating pane the client minimized. The last pane restored is drawn on top and focused. `scroll-pane --pane` on a floating pane the client minimized is refused with ` is minimized; restore it first`.