aws / aws/amazon-q-developer-cli

Feature: JSON and Streaming-JSON output formats for `q chat` (automation/TUI/CI)

Open
#2,713 2 comments 3 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2k
Forks
439
PR merge metrics
No merged PRs in 30d

Description

## Summary
Please add **machine-readable output formats** to `q chat`, equivalent to:
- `--output-format json` (single JSON result with metadata)
- `--output-format stream-json` (newline-delimited JSON events for streaming)

This would enable robust integrations for **TUI/GUI wrappers, CI/CD, and headless workflows** without brittle text parsing.

## Motivation
Today, `q chat --no-interactive` prints **plain text/Markdown**. While some subcommands (e.g., `q settings`, `q whoami`) support `-f json|json-pretty`, there is no way to get **structured chat output** from `q chat`. For programmatic consumption, teams resort to “prompt-enforced JSON,” which is fragile (model drift, system messages, tool output, formatting changes, etc.). A first-class JSON output would:
- Make **parsing deterministic** (no ANSI, no guidance text)
- Provide **usage/cost/duration** metadata for observability
- Support **real-time UIs** via streaming (JSON Lines / NDJSON)

## Prior art
- **Claude Code CLI** supports `--output-format json` and `--output-format stream-json`, plus `--input-format stream-json` for headless pipelines. Many dev tools rely on these to build TUIs, dashboards, and CI checks.

## Proposed UX

### Flags
- `q chat ... --output-format json`
- `q chat ... --output-format stream-json`
- Optional alias: `-f json | json-pretty | stream-json`
- Default remains `plain` for terminal UX parity

### Non-interactive
- Works with `--no-interactive` and respects `--trust-all-tools` / permission modes
- Guarantees **no extra guidance text** or non-JSON artifacts in JSON modes
- Exit codes remain meaningful (non-zero on error)

### Schemas (suggested, minimal)

**JSON (single object)**
```json
{
"type": "result",
"subtype": "success",
"result": "final assistant message as text/markdown",
"usage": { "input_tokens": 0, "output_tokens": 0 },
"total_cost_usd": 0.0,
"duration_ms": 0,
"session_id": "q-xxxxx",
"is_error": false
}
```

**Streaming JSON (one JSON object per line)**
- `{"type":"system","subtype":"init", ...}` – session/model info
- `{"type":"user", ...}` – user turn
- `{"type":"assistant", ...}` – assistant turn (chunked OK)
- `{"type":"tool_use", ...}` / `{"type":"tool_result", ...}` – tool I/O
- `{"type":"result","subtype":"success|error", ...}` – **final** summary event with usage/cost

_Example (abbreviated JSONL):_
```json
{"type":"system","subtype":"init","session_id":"q-123"}
{"type":"user","content":"hello"}
{"type":"assistant","content":"Hi! How can I help you?"}
{"type":"result","subtype":"success","duration_ms":532,"total_cost_usd":0.0012}
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.