Struct CliEmitter 

pub struct CliEmitter<W: Write> { /* private fields */ }

Stateful emitter for structured CLI executions.

The output format, redaction policy, and stream routing are fixed when the emitter is created. Emitting after a terminal event, emitting a repeated terminal event, and writer failures all return explicit errors.

Routing follows the consumption mode (OutputTo):

• CliEmitter::finite / CliEmitter::finite_with — finite one-shot: result → the primary writer (stdout), error/progress/log → the diagnostic writer (stderr). This is the recommended default for a one-shot CLI, so shell capture and pipelines never treat a failure as data.
• CliEmitter::stream — event stream: every event, including error, goes to the single writer, preserving interleaved ordering.
• CliEmitter::from_output_to builds either shape from a parsed OutputTo selector.

Implementations

impl<W: Write> CliEmitter<W>

pub fn new(writer: W, format: OutputFormat) -> Self

Create an event-stream emitter: every event goes to writer.

Alias for CliEmitter::stream. Use CliEmitter::finite for a one-shot command that should split result/error across stdout/stderr.

pub fn with_options( writer: W, format: OutputFormat, output_options: OutputOptions, ) -> Self

Create an event-stream emitter with custom output options.

pub fn stream(writer: W, format: OutputFormat) -> Self

Create an event-stream emitter: every event, including error, goes to the single writer, preserving interleaved ordering. Pick this when the consumer reads one ordered stream and branches on kind.

pub fn finite_with( result_writer: W, diagnostic: impl Write + 'static, format: OutputFormat, ) -> Self

Create a finite one-shot emitter with explicit sinks: result goes to result_writer, while error/progress/log go to diagnostic.

pub fn finite_with_options( result_writer: W, diagnostic: impl Write + 'static, format: OutputFormat, output_options: OutputOptions, ) -> Self

Create a finite one-shot emitter with explicit sinks and output options.

pub fn with_strict_protocol(self) -> Self

Require the AFDATA recommended strict profile for every emitted event.

pub fn with_log_fields<F>(self, provider: F) -> Self

where F: Fn() -> Value + 'static,

Set a provider for default log fields.

The provider is called for every log event (via emit_log or emit with kind:log). Its output is merged as extension fields; explicit call-site fields take precedence.

pub fn emit(&mut self, event: Event) -> Result<(), CliEmitterError>

Emit a typed Event (unified entry for all event kinds).

Accepts only SDK-constructed Event; for dynamic JSON, use emit_validated_value.

pub fn emit_validated_value( &mut self, value: Value, ) -> Result<(), CliEmitterError>

Emit and validate dynamic JSON, then apply redaction/formatting/write.

Runs strict validation first, ensuring the dynamic JSON is safe.

pub fn emit_result(&mut self, payload: Value) -> Result<(), CliEmitterError>

Convenience: build and emit a result event.

pub fn emit_error( &mut self, code: &str, message: &str, ) -> Result<(), CliEmitterError>

Convenience: build and emit an error event.

pub fn emit_progress(&mut self, message: &str) -> Result<(), CliEmitterError>

Convenience: build and emit a progress event.

pub fn emit_log( &mut self, level: LogLevel, message: &str, ) -> Result<(), CliEmitterError>

Convenience: build and emit a log event with default fields.

Applies log_fields_provider if configured; explicit fields take precedence.

pub fn finish(&mut self, event: Event, success_code: u8) -> u8

Emit event as the terminal event and resolve the outcome to a process exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.

A successful write returns success_code; a broken pipe (the reader hung up) returns 0; any other write or validation failure returns 4. A library never calls process::exit itself — return this code from main (std::process::ExitCode::from(code)).

pub fn finish_result(&mut self, payload: Value) -> u8

Convenience over CliEmitter::finish: emit a result payload and return 0 on success.

For an error, build it with json_error (.hint(…), .retryable(…), .field(…) as needed) and pass the event to CliEmitter::finish with the desired exit code — the builder is the error type, so no separate error-emitting convenience is needed.

pub fn into_inner(self) -> W

Access the underlying writer.

impl CliEmitter<Stdout>

pub fn finite(format: OutputFormat) -> Self

Create a finite one-shot emitter wired to the process streams: result → stdout, error/progress/log → stderr. The recommended default for a one-shot CLI.

pub fn finite_options( format: OutputFormat, output_options: OutputOptions, ) -> Self

Create a finite one-shot emitter wired to the process streams, with custom output options.

impl CliEmitter<Box<dyn Write>>

pub fn from_output_to(selector: OutputTo, format: OutputFormat) -> Self

Build an emitter from a parsed OutputTo selector, wired to the process streams: Split is finite mode (result → stdout, everything else → stderr); Stdout/Stderr are event-stream mode onto that stream.

pub fn from_output_to_with( selector: OutputTo, format: OutputFormat, output_options: OutputOptions, ) -> Self

As CliEmitter::from_output_to, with custom output options.