[DOCS] `--input-format stream-json` usage is undocumented beyond the CLI flags table

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/cli-reference
https://code.claude.com/docs/en/headless

Section/Topic

CLI reference > CLI flags table, and the "Run Claude Code programmatically" (headless) page.

Current Documentation

The CLI reference lists the flag in a single row:

--input-format | Specify input format for print mode (options: text, stream-json) | claude -p --output-format json --input-format stream-json

The headless page does not mention --input-format at all. It only covers output streaming.

What's Wrong or Missing?

There is no documentation explaining how to use --input-format stream-json. Specifically:

1. What message format should be sent on stdin? What JSON structure does the CLI expect? What are the valid message types?
2. How do you send follow-up messages? Can you send multiple user messages to create a multi-turn conversation via stdin?
3. How does it interact with --output-format stream-json? When using both together, what's the expected bidirectional flow?
4. What happens when the CLI sends a permission request? How do you respond via stdin?

The Agent SDK docs have thorough coverage of streaming input (platform.claude.com/docs/en/agent-sdk/streaming-vs-single-mode), but this doesn't help users who want to use the CLI directly via claude -p with structured input.

This gap is significant because --input-format stream-json is the only CLI mechanism for programmatic bidirectional communication with Claude Code in print mode.

Suggested Improvement

Add a section to the headless page (or a new dedicated page) covering:

1. The NDJSON message format expected on stdin when using --input-format stream-json
2. Example of sending a user message and reading the response
3. Example of multi-turn conversation via stdin/stdout
4. How permission prompts work in this mode (or a pointer to --permission-prompt-tool)
5. A complete example showing bidirectional streaming (send input, read streaming output, send follow-up)

At minimum, link to the Agent SDK's streaming input documentation from the CLI reference flag description, noting the message format is the same.

Impact

High - Prevents users from using a feature

Additional Context

Third-party projects like The Vibe Companion have resorted to reverse-engineering the internal WebSocket NDJSON protocol because the documented CLI interface doesn't explain how to use bidirectional streaming. If --input-format stream-json were properly documented, developers could build programmatic integrations using the supported CLI interface instead of exploiting hidden flags.

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] --permission-prompt-tool flag has no usage documentation #24595
2. [DOCS] CLI flag --replay-user-messages required for file checkpointing but not in CLI reference #20763
3. [BUG] --max-turns CLI option is undocumented in --help and official documentation #16963

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[niclaslindstedt]

I came here looking for documentation on this feature.

[coygeek]

I dug through The-Vibe-Company/companion so others don’t have to. Here’s what appears to be proven by code vs inferred from reverse-engineering notes.

What is proven from the companion source

1. It is a wrapper around the real claude CLI binary (not a reimplementation of the model runtime).

   • Resolves claude from PATH and spawns it as a subprocess:
     https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/cli-launcher.ts#L184-L192

2. It launches Claude Code with the exact streaming/programmatic flags discussed in this issue:

   • --sdk-url
   • --print
   • --output-format stream-json
   • --input-format stream-json
   • -p ""
   • Source: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/cli-launcher.ts#L194-L231
   • Test asserting those args: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/cli-launcher.test.ts#L114-L140

3. The CLI is expected to connect back as a WebSocket client to /ws/cli/:sessionId.

   • Source: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/index.ts#L90-L100

4. The message envelope used to send prompts is explicit:

   • {"type":"user","message":{"role":"user","content":...},"parent_tool_use_id":null,"session_id":...} (NDJSON line)
   • Source: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/ws-bridge.ts#L623-L630

5. Permission flow is explicit and bidirectional:

   • Incoming control_request with subtype can_use_tool
   • Outgoing control_response with allow/deny
   • Source (handler): https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/ws-bridge.ts#L522-L671
   • Source (tests): https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/ws-bridge.test.ts#L611-L643 and https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/ws-bridge.test.ts#L811-L878

6. The system/init payload fields they parse include the exact metadata many users need documented (session_id, tools, mcp_servers, model, permissionMode, apiKeySource, claude_code_version, slash_commands, optional agents/skills).

   • Type definitions: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/session-types.ts#L5-L21
   • Init handling: https://github.com/The-Vibe-Company/companion/blob/7ac7886/web/server/ws-bridge.ts#L370-L389

What is likely/inferred (not official docs)

The repo’s reverse-engineered protocol doc claims:

• hidden --sdk-url behavior,
• NDJSON parity with stream-json transport,
• internal transport class names and auth header details.

Those claims are in:
https://github.com/The-Vibe-Company/companion/blob/7ac7886/WEBSOCKET_PROTOCOL_REVERSED.md#L1-L90

Useful signal, but still reverse-engineered and therefore not authoritative documentation.

Why this matters for this docs issue

Even without relying on reverse-engineering claims, companion’s implementation/tests strongly indicate that --input-format stream-json is part of a real bidirectional control path (not just a trivial flag-table option). The missing docs are forcing developers to infer message schema and control flow from third-party code.

A minimal official doc section with:

• required message envelope(s),
• multi-turn sequencing,
• permission request/response exchange,
• and how this maps to --output-format stream-json

would remove a lot of guesswork.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.