hty snapshot

Capture the current state of a session’s terminal screen.

The <session> argument accepts a session name, a full UUID, or a unique UUID prefix. If only one session is running, you can omit it.

Reference

hty snapshot [SESSION] [--ansi] [--json]

Read the session's current rendered screen. Default output is plain
text. Use --ansi to get the styled ANSI rendering, --json for the full
structured response.

Default output

By default, hty snapshot prints the rendered screen as plain text — no escape codes, no JSON wrapper. This is the same content a human would see in the terminal.

JSON output

With --json, the output includes structured metadata:


{
  "ok": true,
  "snapshot": {
    "rows": 24,
    "cols": 80,
    "cursor_row": 1,
    "cursor_col": 1,
    "title": "notes.txt - VIM",
    "buffer": "hello world\n~\n~\n...",
    "screen_ansi": "\u001b[?25l\u001b[H...",
    "lines": ["hello world", "~", "~"],
    "status": "running"
  }
}

Field	Description
`buffer`	Plain text screen, rows joined by `\n`. ANSI codes stripped.
`screen_ansi`	Same screen with ANSI escape codes preserved.
`lines`	Each row as a separate string in an array.
`cursor_row`, `cursor_col`	Cursor position, 1-indexed.
`title`	Window title set by the program, or `null`.
`status`	Session status: `running`, `exited`, `failed`, or `killed`.

Parsing the output

Pipe the JSON output to jq to extract specific parts of the screen:


# Print the full plain-text screen
hty snapshot my-session --json | jq -r '.snapshot.buffer'
 
# Read the first line of the screen
hty snapshot my-session --json | jq -r '.snapshot.lines[0]'
 
# Check whether the session is still running
hty snapshot my-session --json | jq -r '.snapshot.status'

Use the default plain-text output for simple text matching. Use --json when you need cursor position, status, or structured line access. Use --ansi when you need color information.