# Debug commands (/docs/v0.4/cli/debug)



`koshi debug` prints diagnostics. Both subcommands accept `--format table`
(default) or `--format json`.

## `debug dump-state` [#debug-dump-state]

```bash
koshi debug dump-state
koshi debug dump-state --format json
```

Prints every running session, with its tabs, panes, and clients. Every session
answers this command.

## `debug dump-layout` [#debug-dump-layout]

```bash
koshi debug dump-layout
koshi debug dump-layout --tab <NAME_OR_ID>
koshi debug dump-layout --format json
```

Prints, for each tab: its split tree, the solved rectangles, panes with no room,
stacks, and per-client focus.

Every client viewing one tab shares one set of sizes. The tab solves against the
smallest viewing terminal on each axis, minus the top tab bar row and the bottom
hint row. Two clients on one tab, one 80x24 and one 120x40, both print
`viewport 80x22`.

What is per client is the view: one client tiled and one with a pane fullscreen
give that tab two sets of rectangles. A tab no client is viewing prints its tree
and no rectangles.

## `debug events` [#debug-events]

```bash
koshi debug events
koshi debug events --since 30s --filter pane --format json
```

Prints the last 1000 events each running session published, oldest first. Each
row names the time, event, session, client, tab, and pane ids. It never prints
command lines, pane output, or typed characters. A keystroke appears as
`PaneTyped`.

`--since` keeps events within a duration such as `30s`, `5m`, `2h`, or `7d`.
`--filter` keeps event names containing the given text, ignoring case. A
session started by an older koshi has no event buffer; the command says so.

A shell that emits OSC 133 prompt markers publishes `PaneCommandStarted` and
`PaneCommandFinished` for each command. Each event names only the pane and
never the command line or its output.

## Command arguments are masked [#command-arguments-are-masked]

A pane's command arguments print as `***`; the program name stays visible.

```text
mysql ***
```

A pane running `mysql -pHUNTER2` prints as `mysql ***`. Use
`koshi inspect pane` when you need the command in full.

## Sessions older than this binary [#sessions-older-than-this-binary]

A session that started before you installed this koshi cannot report its
layout. `dump-layout` says so and names what to do: restart that session, or
run `dump-state`, which every session answers.