# How to Enable Streaming Output in OpenClaude: A Complete Guide

> Learn how to enable streaming output in OpenClaude. Follow this guide to set up headless mode, output formats, and verbose flags for seamless results.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**To enable streaming output in OpenClaude, run the CLI in headless mode with `--print`, set `--output-format=stream-json`, and include the `--verbose` flag.**

OpenClaude supports real-time **streaming output** via NDJSON, allowing applications to process tokens as they are generated rather than waiting for complete responses. This article explains how to activate and consume the streaming interface based on the official `Gitlawb/openclaude` source code.

## Prerequisites for OpenClaude Streaming

Streaming output in OpenClaude requires three specific conditions to be met simultaneously. The implementation in [`src/cli/print.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/print.ts) enforces these constraints strictly.

### 1. Enter Headless Mode with `--print`

The `-p` or `--print` flag disables the interactive UI and directs output to stdout. Without this flag, OpenClaude launches its conversational interface, which does not support streaming protocols.

```bash
openclaude -p "Your prompt here"

```

### 2. Select the Streaming Format

Set `--output-format=stream-json` to enable NDJSON output. This flag is defined in [`web/src/data/cliFlags.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts) at line 42 alongside other format options.

```bash
openclaude -p --output-format=stream-json "Your prompt here"

```

### 3. Enable Verbose Logging

The [`print.ts`](https://github.com/Gitlawb/openclaude/blob/main/print.ts) implementation contains an explicit guard at lines 886–888 that throws an error if `--verbose` is missing when `stream-json` is requested.

```bash
openclaude -p --output-format=stream-json --verbose "Your prompt here"

```

## Optional: Include Partial Messages

For intermediate tokens and partial generations, add `--include-partial-messages`. This flag, documented at lines 46–47 of [`web/src/data/cliFlags.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts), exposes the model's incremental output rather than buffering until complete sentences finish.

```bash
openclaude -p --output-format=stream-json --verbose --include-partial-messages "Write a story."

```

## Complete Command Examples

### Basic Streaming Usage

```bash

# Minimal working command for streaming JSON output

openclaude -p --output-format=stream-json --verbose "Explain recursion in 3 sentences."

```

### Consume with `jq`

Pipe the NDJSON stream to `jq` for real-time content extraction:

```bash
openclaude -p --output-format=stream-json --verbose "List three JavaScript array methods." |
  jq -c '.content'

```

Each line prints as it arrives, enabling responsive downstream processing.

### Using the Official SDK

The `@openclaude/sdk` package forwards the same constraints to the CLI internally:

```typescript
import { OpenClaude } from '@openclaude/sdk'

const client = new OpenClaude({ /* authentication config */ })

const stream = client.query({
  prompt: 'Summarize the plot of "Inception".',
  outputFormat: 'stream-json',
  verbose: true,
})

for await (const chunk of stream) {
  console.log('Received:', chunk)
}

```

The `outputFormat` option is defined in [`src/entrypoints/sdk/coreSchemas.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/coreSchemas.ts) and accepts `'stream-json'` as a valid value.

## Key Source Files for Streaming Implementation

Understanding the codebase helps debug streaming issues:

| File | Purpose |
|------|---------|
| [`web/src/data/cliFlags.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts) | Flag definitions including `--output-format` and `--include-partial-messages` |
| [`src/cli/print.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/print.ts) | Headless printer implementation; enforces `--verbose` requirement at lines 886–888 |
| [`src/utils/streamJsonStdoutGuard.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/streamJsonStdoutGuard.ts) | Guards `process.stdout.write` to ensure valid NDJSON output |
| [`src/cli/headlessHeartbeat.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/headlessHeartbeat.ts) | Manages optional heartbeat events during streaming sessions |
| [`src/entrypoints/sdk/coreSchemas.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/coreSchemas.ts) | SDK schema with `outputFormat: 'stream-json'` option |

## Common Errors and Resolutions

| Error | Cause | Fix |
|-------|-------|-----|
| "Streaming output requires verbose mode" | Missing `--verbose` flag | Add `--verbose` to your command |
| "Invalid output format" | Typo in format string | Use exactly `stream-json` |
| Interactive UI launches | Forgot `--print` flag | Include `-p` or `--print` |

## Summary

- **Headless mode (`--print`)** is mandatory for streaming output in OpenClaude
- **`--output-format=stream-json`** selects the NDJSON protocol
- **`--verbose`** is enforced by [`src/cli/print.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/print.ts) and cannot be omitted
- **`--include-partial-messages`** exposes incremental tokens for real-time applications
- The `@openclaude/sdk` abstracts these flags for programmatic usage

## Frequently Asked Questions

### What NDJSON format does OpenClaude streaming use?

Each line of stdout is a complete, parseable JSON object. The [`src/utils/streamJsonStdoutGuard.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/streamJsonStdoutGuard.ts) module intercepts writes to guarantee this structure, preventing malformed chunks from corrupting the stream.

### Can I use streaming with the interactive UI?

No. Streaming output requires headless mode (`--print`). The interactive interface manages its own rendering loop and does not expose raw token streams.

### Why does streaming require `--verbose`?

According to the source code in [`src/cli/print.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/print.ts) (lines 886–888), verbose logging ensures sufficient metadata is available for each streamed chunk. This design decision links diagnostic detail with streaming capability.

### How do I handle connection interruptions during streaming?

The [`src/cli/headlessHeartbeat.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/cli/headlessHeartbeat.ts) module emits optional heartbeat events you can monitor. Implement client-side retry logic that detects missing heartbeats and re-establishes the stream with your last successful sequence number.