Add -o/--output flag to dictate command for text/json modes (#192)

Adds an `-o`/`--output` option to the `assembly dictate` command that
allows users to explicitly choose between `text` (bare transcript,
pipe-friendly) and `json` (one JSON object per utterance) output modes.

## Summary

This change introduces output mode selection to the dictate command,
bringing it into alignment with the `stream` and `agent` commands'
output handling patterns. The new flag provides an explicit,
discoverable way to select output format while maintaining backward
compatibility (text remains the default).

## Key Changes

- **New `output_field` parameter** in `DictateOptions` to capture the
`-o`/`--output` choice
- **Output mode resolution** via `resolve_output_modes()` in
`run_dictate()` to:
  - Fold `-o json` into `json_mode` (equivalent to `--json`)
- Reject the contradictory `--json + -o text` combination with a
`UsageError`
- **CLI integration** in `dictate/__init__.py`:
  - Added `choices.TextOrJson` enum option
  - Wired the parameter through to `DictateOptions`
  - Updated help text and examples to show the new usage pattern
- **Test coverage** for all three scenarios:
  - `-o json` enables NDJSON output without the `--json` flag
  - `-o text` emits bare transcript (no JSON wrapper)
  - `--json + -o text` raises `UsageError` as a usage conflict

## Implementation Details

The implementation reuses the existing `resolve_output_modes()` utility
from the streaming session module, ensuring consistent conflict
detection and resolution across commands. The dictate command's
`text_mode` half of the resolution is unused (plain text is already the
non-JSON default in `_emit()`), but the infrastructure is in place for
future enhancements.

https://claude.ai/code/session_01Knhve9pgqPSg2kQhxnV7Wn

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

aai_cli/commands/dictate/__init__.py

@@ -5,6 +5,7 @@
 from aai_cli import command_registry, help_panels, options
 from aai_cli.app.context import run_with_options
 from aai_cli.commands.dictate import _exec as dictate_exec
+from aai_cli.core import choices
 from aai_cli.core.sync_stt import MAX_AUDIO_SECONDS
 from aai_cli.ui.help_text import examples_epilog
 
@@ -29,6 +30,7 @@
                 "assembly dictate --word-boost AssemblyAI --word-boost LeMUR",
             ),
             ("One JSON object per utterance", "assembly dictate --json"),
+            ("Pipe the bare transcript onward", "assembly dictate -o text | assembly llm -f"),
         ]
     ),
 )
@@ -58,6 +60,12 @@ def dictate(
         max=float(MAX_AUDIO_SECONDS),
     ),
     json_out: bool = options.json_option("Emit one JSON object per utterance"),
+    output_field: choices.TextOrJson | None = typer.Option(
+        None,
+        "-o",
+        "--output",
+        help="Output mode: text (the bare transcript per utterance, pipe-friendly) or json",
+    ),
 ) -> None:
     """Push-to-talk dictation: record the mic, get the transcript back
 
@@ -73,5 +81,6 @@ def dictate(
         device=device,
         once=once,
         max_seconds=max_seconds,
+        output_field=output_field,
     )
     run_with_options(ctx, dictate_exec.run_dictate, opts, json=json_out)

aai_cli/commands/dictate/_exec.py

@@ -13,10 +13,11 @@
 from dataclasses import dataclass
 
 from aai_cli.app.context import AppState
-from aai_cli.core import sync_stt
+from aai_cli.core import choices, sync_stt
 from aai_cli.core.config_builder import split_csv
 from aai_cli.core.hotkey import CTRL_C, CTRL_D, ESC, TerminalKeys
 from aai_cli.core.microphone import MicrophoneSource
+from aai_cli.streaming.session import resolve_output_modes
 from aai_cli.ui import output
 
 # Capture is resampled to one rate the Sync API accepts; 16 kHz mono PCM16 keeps
@@ -41,6 +42,8 @@ class DictateOptions:
     device: int | None
     once: bool
     max_seconds: float
+    # -o/--output: text (the default bare-transcript shape) or json (== --json).
+    output_field: choices.TextOrJson | None = None
 
 
 def _note(message: str, *, json_mode: bool, quiet: bool) -> None:
@@ -165,6 +168,11 @@ def _session(
 
 def run_dictate(opts: DictateOptions, state: AppState, *, json_mode: bool) -> None:
     """Execute one `assembly dictate` invocation from already-parsed flags."""
+    # Fold -o/--output into json_mode (-o json == --json) and reject the
+    # contradictory --json + -o text pair, the same way `stream`/`agent` do.
+    # dictate has no live panel, so the text_mode half is unused — plain
+    # transcript text is already the non-JSON default in `_emit`.
+    _, json_mode = resolve_output_modes(opts.output_field, json_mode=json_mode)
     try:
         # Entering TerminalKeys validates the terminal (a usage precondition)
         # before credentials, so a piped stdin reads as "needs a terminal" — not

tests/__snapshots__/test_snapshots_help_run.ambr

@@ -373,6 +373,10 @@
   │                                                   [default: 120.0]           │
   │ --json         -j                                 Emit one JSON object per   │
   │                                                   utterance                  │
+  │ --output       -o      [text|json]                Output mode: text (the     │
+  │                                                   bare transcript per        │
+  │                                                   utterance, pipe-friendly)  │
+  │                                                   or json                    │
   │ --help                                            Show this message and      │
   │                                                   exit.                      │
   ╰──────────────────────────────────────────────────────────────────────────────╯
@@ -388,6 +392,8 @@
    $ assembly dictate --word-boost AssemblyAI --word-boost LeMUR
    One JSON object per utterance
    $ assembly dictate --json
+   Pipe the bare transcript onward
+   $ assembly dictate -o text | assembly llm -f
 
 
 

tests/test_dictate_exec.py

@@ -16,8 +16,8 @@
 
 from aai_cli.app.context import AppState
 from aai_cli.commands.dictate import _exec as dictate_exec
-from aai_cli.core import config, sync_stt
-from aai_cli.core.errors import CLIError
+from aai_cli.core import choices, config, sync_stt
+from aai_cli.core.errors import CLIError, UsageError
 
 DICTATE_DEFAULTS = dictate_exec.DictateOptions(
     language=None,
@@ -145,6 +145,34 @@ def test_json_mode_emits_one_ndjson_object_per_utterance(seams, capsys):
     assert captured.err == ""
 
 
+def test_output_json_folds_into_ndjson_without_the_json_flag(seams, capsys):
+    # -o json must enable NDJSON on its own (json_mode stays the --json flag,
+    # which is False here) — proving the -o/--output resolution runs.
+    seams["keys"] = FakeKeys(["\r", "\r"])
+    _run(dataclasses.replace(DICTATE_DEFAULTS, output_field=choices.TextOrJson.json))
+    assert json.loads(capsys.readouterr().out)["text"] == "hello world"
+
+
+def test_output_text_emits_bare_transcript(seams, capsys):
+    # -o text is the explicit spelling of the human default: bare text, no JSON.
+    seams["keys"] = FakeKeys(["\r", "\r"])
+    _run(dataclasses.replace(DICTATE_DEFAULTS, output_field=choices.TextOrJson.text))
+    out = capsys.readouterr().out
+    assert out.strip() == "hello world"
+    assert "{" not in out
+
+
+def test_output_text_conflicts_with_json_flag(seams):
+    # --json + -o text are contradictory output shapes: a clean usage error,
+    # the same as `stream`/`agent`.
+    seams["keys"] = FakeKeys(["\r", "\r"])
+    with pytest.raises(UsageError):
+        _run(
+            dataclasses.replace(DICTATE_DEFAULTS, output_field=choices.TextOrJson.text),
+            json_mode=True,
+        )
+
+
 def test_quiet_suppresses_the_interactive_hints(seams, capsys):
     seams["keys"] = FakeKeys(["\r", "\r"])
     _run(state=AppState(quiet=True))