---
title: "Terminal UI"
description: "Connect the standalone XSAF terminal client to a remote agent."
---

> Documentation Index
> Fetch the complete documentation index at: https://xsaf.ilha.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal UI

## Install

```sh
npm install --global @xsaf/cli
```

`@xsaf/cli` requires Node.js 22.19 or newer.

## Expose streaming chat

Register the authenticated HTTP channel on the server-owned agent:

```ts
import { agent } from "@xsaf/agent";
import http from "@xsaf/agent/channel/http";

const bot = agent(config).channel(
  http({
path: "/chat",
apiKey: process.env.API_KEY,
  }),
);

await bot.start();
```

The channel streams response chunks and tool/delegate lifecycle events over one SSE response. The agent remains entirely inside the server process.

## Open the standalone client

```sh
API_KEY=asd123 xsaf -u http://localhost:3000
```

The CLI uses `API_KEY` as a bearer token. It owns stdin and stdout independently from the HTTP server, so server logs and reloads cannot corrupt terminal rendering.

Useful options:

```text
-u, --url       XSAF server base URL
-s, --session   Session identifier (default: tui)
--name           Agent name shown in the terminal
```

The UI provides a multiline editor, prompt history, Markdown responses, throttled streaming, bounded history, and live tool/delegate statuses.

## Embedded rendering

Applications that intentionally run an agent in the terminal process can still use the rendering factory:

```ts
import tui from "@xsaf/cli";

const chat = tui({ agent });
chat.start();
```

The controller exposes `start()`, `stop()`, `submit()`, `addMessage()`, and `setStatus()` without exposing Pi TUI internals.

## Next steps

- [Configure an agent](/xsaf)
- [Review Tools & Security](/recipes/tools)
- [Test without tokens](/recipes/testing)

Source: https://xsaf.ilha.build/recipes/tui/index.mdx