> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ANSI features and TUI detection

> ANSI colours, cursor movement, tput queries, and text styles through the sandbox PTY — proving full terminal emulation works.

This cookbook proves that the sandbox PTY is a fully capable
`xterm-256color` terminal. Every byte the shell emits — including
raw ANSI escape sequences — streams back through the SSE pipe and
renders on your local terminal unchanged.

## What you'll learn

* Querying `$TERM`, `tput colors`, and `tty` inside the sandbox
* Rendering the 16-colour and 256-colour ANSI palettes
* Text styles: bold, underline, reverse, blink
* Cursor save/restore and absolute positioning
* Using `tput` abstractions alongside raw escape codes
* Bracketed-paste toggle and ncurses TTY detection

## Prerequisites

<Snippet file="snippets/env-setup.mdx" />

```bash theme={null}
pip install declaw
```

## Code walkthrough

The script opens a PTY and drives nine mini-tests through
`handle.send_stdin()`. A small helper sends a command and sleeps
briefly to let output flush:

```python theme={null}
def send(handle, cmd: str, settle: float = 0.3) -> None:
    handle.send_stdin(cmd + "\n")
    time.sleep(settle)
```

### 1. TERM value + tput

```python theme={null}
send(handle, 'echo "TERM=$TERM"')   # → xterm-256color
send(handle, "tput colors")          # → 256
send(handle, "tty")                  # → /dev/pts/0
```

### 2. ANSI 16-colour palette

```python theme={null}
send(handle,
    r"for i in 0 1 2 3 4 5 6 7; do "
    r"printf '\e[4%dm %d \e[0m' $i; done; echo")
```

Eight background-coloured cells, one per ANSI base colour.

### 3. Text styles

```python theme={null}
send(handle,
    r"printf '\e[1mBOLD\e[0m  \e[4mUNDERLINE\e[0m  "
    r"\e[7mREVERSE\e[0m  \e[5mBLINK\e[0m\n'")
```

### 4. 256-colour palette

A 16x16 grid of `\e[48;5;Nm` background cells covering the full
256-colour cube.

### 5. Cursor save/restore + absolute move

```python theme={null}
send(handle,
    r"printf 'before \e[s\e[5;40HJUMPED-TO-(5,40)\e[u AFTER\n'")
```

The cursor jumps to row 5 col 40, prints a label, then restores back.

### 6-9. tput abstractions, bracketed paste, TTY detection

The remaining sections use `tput setaf`, toggle bracketed-paste mode,
and confirm `test -t 0` reports stdin as a TTY with `stty size`
matching the requested dimensions.

## Running it

```bash theme={null}
export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="api.declaw.ai"
python cookbook/examples/pty-features/main.py
```

Use an xterm-compatible terminal (iTerm2, Alacritty, Kitty, or any
tmux pane) so the ANSI output renders correctly.

## How it works

Every escape sequence is generated by the shell running inside the
sandbox. The bytes travel through the SSE stream to `on_data`, which
writes them directly to your local `stdout.buffer`. Your terminal
emulator does the actual rendering — the SDK never interprets or
strips ANSI codes.

## Full source

See `cookbook/examples/pty-features/main.py` in the repo.