hty run

Start a program in a new detached PTY session. The session runs in the background — use watch, snapshot, or attach to interact with it.

Reference

hty run [--name NAME] [--rows N] [--cols N] [--cwd PATH] [--scrollback N] -- program [args...]

Create a new session and start `program` inside a fresh PTY. The session
is detached from your terminal; observe it with `hty watch` and drive it
with `hty send`/`hty snapshot`/`hty wait`.

Flags:
  --name NAME       Human-friendly alias for the session. Must be unique.
  --rows N          Initial row count (default 24)
  --cols N          Initial column count (default 80)
  --cwd PATH        Child's working directory
  --scrollback N    Scrollback buffer size (default 10000)

Wait + snapshot flags (let `run` block until the program is ready and
return the initial render in one round-trip):
  --snapshot                Include the post-spawn snapshot in the response.
                            Requires one of --wait-until-* or --wait-duration.
  --wait-duration DUR       Sleep DUR after spawn, then snapshot.
  --wait-until-idle [MS]    Block until the screen has been quiet for MS
                            milliseconds (default 100).
  --wait-until-text STR     Block until STR appears in the rendered buffer.
  --wait-until-regex RE     Block until RE (POSIX extended) matches.
  --wait-until-exit         Block until the child process exits.
  --timeout DUR             Cap on any --wait-until-* (default 30s; 0 = none).
  --ansi                    With --snapshot, print styled ANSI rendering.

`-d` / `--detach` is accepted as a no-op — every `hty run` session is
detached by default. Use `hty attach` for an interactive view.

Example:
  hty run --name debug-vim -- vim /tmp/foo.txt
  hty run --name app --snapshot --wait-until-idle -- create-next-app my-app

Examples

# Simple session
hty run -- vim /tmp/notes.txt
 
# Named session with custom terminal size
hty run --name my-vim --rows 40 --cols 120 -- vim /tmp/notes.txt
 
# With working directory
hty run --name build --cwd /my/project -- npm test