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", "~", "~"],
    "cells": [["h", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d", " ", "..."], ["~", " ", "..."]],
    "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`.
`cells`	2D array shaped `[rows][cols]`, where each entry is the glyph at that column. Lets you reason about column-accurate coordinates — wide characters (e.g. CJK) occupy their starting column and their trailing cell is reported separately, so you can map a visual position to an exact `(row, col)` without re-tokenizing `buffer`.
`mouse`	Per-session mouse-input mode, inferred from `CSI ?1000/1002/1003 h/l` (event set) and `?1006 h/l` (SGR extended) toggles observed on the output stream. Fields: `enabled` (true when any event-set mode is on — the gate `hty send --click` checks), `x10` (?1000), `button_event` (?1002), `any_event` (?1003), `sgr` (?1006).

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.