nvflare.tool.cli_output module

Stream contract for all nvflare CLI command handlers

Current default (human-first):

stdout — human-readable output (tables, summaries, prompts). stderr — errors and diagnostics.

JSON output mode (–format json):

stdout — exactly one JSON envelope per command invocation:

{“schema_version”: “1”, “status”: “ok”|”error”, “data”: {…}}

stderr — all human-readable output: progress, warnings, prompts, diagnostics.

JSON Lines output mode (–format jsonl):

stdout — newline-delimited JSON events for streaming commands. stderr — all human-readable output: progress, warnings, prompts, diagnostics.

Exceptions (plain text, outside the JSON contract):

–help / -h argparse usage text; agents use –schema instead –version top-level utility path, not command output argparse errors unrecognised-argument messages generated by argparse

get_connect_timeout() → float

is_json_mode() → bool

Public helper for checking JSON mode without exposing internals.

is_jsonl_mode() → bool

Public helper for checking JSON Lines mode without exposing internals.

output(data: Any, fmt: str | None) → None

Legacy output helper used by older cert/package command paths.

output_error(error_code: str, exit_code: int = 1, hint: str | None = None, data: Any | None = None, detail: str | None = None, **kwargs) → None

Print an error from ERROR_REGISTRY and exit. Never returns.

output_error_message(error_code: str, message: str, hint: str | None = None, fmt: str | None = None, exit_code: int = 1, detail: str | None = None) → None

Print an explicit error message/hint pair and exit. Never returns.

output_jsonl_event(event: Any) → None

Print one JSONL event for streaming command output.

output_ok(data: Any, exit_code: int = 0) → None

Print command success output.

output_usage_error(parser, detail: str, exit_code: int = 4, error_code: str = 'INVALID_ARGS', message: str = 'Invalid arguments.', hint: str = 'Run with -h for usage.') → None

Print usage/help followed by a structured usage error and exit.

print_human(*args, **kwargs)

Print any human-readable text (progress, warnings, tables, diagnostics).

Drop-in replacement for print() in CLI command handlers. Keeps stdout clean for the JSON envelope in JSON output mode. Usage: print_human(“Starting shutdown of NVFLARE”)

prompt_yn(question: str, default_no: bool = True) → bool

Write a Y/N prompt to stderr (json mode) or stdout (human mode) and read the answer from stdin.

Returns True if the user answered Y/y, False otherwise. Writes the prompt to stderr in json mode so that stdout contains only JSON. Callers must check sys.stdin.isatty() and handle –force before calling.

Usage:

if not cmd_args.force:

if not sys.stdin.isatty():

output_error(“INVALID_ARGS”, exit_code=4, detail=”use –force in non-interactive mode”) return

if not prompt_yn(f”Delete job ‘{job_id}’?”):

print_human(“Cancelled.”) return

set_connect_timeout(value: float) → None

Set CLI connection timeout (seconds).

set_output_format(fmt: str) → None

Set the output format for all cli_output functions.

Called once by cli.py after –format is parsed.

Parameters:

fmt – “txt” (default) for human-readable output to stdout/stderr; “json” for a single machine-readable JSON envelope on stdout. “human” is accepted as a backward-compatible alias for “txt”.