Streaming Responses

REST CLI automatically detects and handles streaming HTTP responses.

Supported Streaming Types

Server-Sent Events (SSE)

SSE streams require the @streaming true directive for real-time display:

### Stream Events
# @streaming true
GET https://api.example.com/events
Accept: text/event-stream

IMPORTANT: Without # @streaming true, the request will wait for completion (which never happens for infinite SSE streams!).

Response:

Content-Type: text/event-stream

data: {"event": "user_joined", "user": "alice"}

data: {"event": "message", "text": "Hello!"}

data: {"event": "user_left", "user": "bob"}

Chunked Transfer Encoding

HTTP/1.1 chunked responses are handled transparently:

### Large Dataset
GET https://api.example.com/data/export

Server responds with Transfer-Encoding: chunked, data arrives progressively.

JSON Streaming

Newline-delimited JSON streams:

### Stream JSON
POST https://api.openai.com/v1/chat/completions
Authorization: Bearer {{apiKey}}
Content-Type: application/json

{
  "model": "gpt-4",
  "stream": true,
  "messages": [{"role": "user", "content": "Hello"}]
}

Response arrives as progressive chunks.

Behavior

TUI Mode

Real-Time Streaming:

• Progressive display - data appears in real-time as it arrives
• Auto-scroll - automatically scrolls to show latest data
• Status indicator - shows “Streaming…” with stop instructions
• Cancelation - press q to stop streaming at any time
• Infinite streams - no timeout, streams run until stopped or completed
• Auto-detection happens behind the scenes
• Works with all filtering and parsing features

How it works:

1. Execute a streaming request (SSE, chunked transfer, etc.)
2. Data appears on screen immediately as chunks arrive
3. Viewport auto-scrolls to show the latest content
4. Press q to stop the stream whenever you want
5. Stream completes with “Stream completed” status

CLI Mode

Real-Time Streaming:

• Same auto-detection as TUI (SSE, chunked transfer, JSON streaming)
• Progressive output to stdout as chunks arrive
• Press Ctrl+C to cancel stream at any time
• Works with @streaming true directive
• Output can be piped: restcli run stream.http | jq
• Clean cancellation with “Stream cancelled by user” message

Output:

restcli run stream-events.http
data: {"event": "message", "text": "Hello"}

data: {"event": "message", "text": "World"}

^C
Stream cancelled by user

Enabling Streaming

The @streaming Directive

Use # @streaming true to enable real-time streaming display:

### My SSE Endpoint
# @streaming true
GET https://example.com/events

When to use:

• Infinite streams: SSE, WebSocket upgrades, long-polling
• Real-time data: Live logs, metrics, notifications
• When you need immediate feedback: Don’t want to wait for completion

When NOT to use:

• Regular API requests
• Finite streams that complete quickly
• When you need filtering/querying (not yet supported for streaming)

Technical Details

Detection Logic

Auto-detection happens for non-streaming requests:

// For requests WITHOUT @streaming directive:
Content-Type: text/event-stream           → Buffered
Content-Type: application/stream+json     → Buffered
Transfer-Encoding: chunked                → Buffered

// For requests WITH @streaming true:
All responses                             → Real-time display

Keyboard Controls

TUI Mode

When streaming is active:

• q - Stop the stream immediately
• j/k or arrow keys - Scroll through streamed data (auto-scroll pauses)
• G - Jump to bottom (resume auto-scroll)
• g - Jump to top

CLI Mode

• Ctrl+C - Cancel stream immediately