Documentation
¶
Overview ¶
Package output provides machine-readable output for pgtransfer.
By default pgtransfer prints human-friendly, coloured text. When the global --json flag is set (or PGTRANSFER_JSON=1 is present in the environment), the commands emit a single structured JSON object on stdout instead, so that scripts, CI pipelines and AI agents can parse results reliably without scraping prose.
The JSON contract is intentionally small and stable:
{
"ok": true,
"command": "export csv",
"data": { ... command-specific fields ... },
"error": null
}
On failure:
{
"ok": false,
"command": "export csv",
"data": null,
"error": {"code": "connection_failed", "message": "..."}
}
Index ¶
- func Configure(jsonFlag bool)
- func EnableMCPMode() *os.File
- func IsInteractive() bool
- func IsJSON() bool
- func IsMCP() bool
- func PrintErrorLine(err error)
- func Reset()
- func SetJSON(enabled bool)
- func SetMode(m Mode)
- func SetWriters(out, errW io.Writer)
- func Success(command string, data interface{})
- func WriteJSON(v interface{}) error
- type Error
- type Mode
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Configure ¶
func Configure(jsonFlag bool)
Configure applies explicit settings, typically called once from the root command. When both forceJSON and the environment agree, json wins.
func EnableMCPMode ¶
EnableMCPMode switches the process into MCP server mode.
When pgtransfer speaks the Model Context Protocol over stdio, stdout is reserved for protocol frames: a single stray byte (a progress message, an ANSI escape) corrupts the stream and the client fails to parse it. Third-party libraries, however, print progress messages straight to os.Stdout.
EnableMCPMode therefore redirects the process-level os.Stdout to stderr for the lifetime of the MCP server, so any such output becomes harmless diagnostics. The caller must keep a reference to the real stdout (returned here) and hand it to the MCP transport.
func IsInteractive ¶
func IsInteractive() bool
IsInteractive reports whether writes to stdout are attached to a terminal. Agents and pipelines generally are not, which lets commands suppress spinners and colour automatically.
func IsJSON ¶
func IsJSON() bool
IsJSON reports whether JSON output is currently enabled. It also honours the PGTRANSFER_JSON environment variable when the mode has not been set explicitly, so agents can simply export the variable.
func PrintErrorLine ¶
func PrintErrorLine(err error)
PrintErrorLine writes a human-readable error to stderr. It is a no-op in JSON mode, where the error has already been emitted as part of the result object.
func SetMode ¶
func SetMode(m Mode)
SetMode forces the output mode. Primarily used by tests and by the root command once flags have been parsed.
func SetWriters ¶
SetWriters overrides the output destinations. Intended for tests.
Types ¶
type Error ¶
Error is a structured, machine-readable error.
func Fail ¶
Fail emits a failed result in JSON mode and returns the structured error so the caller can propagate it. Emission happens at most once per process: a command body that reports a failure prevents the top-level handler from emitting a second, less specific error.
Source Files