Documentation
¶
Overview ¶
Package output owns the CLI's stdout/stderr contract. On success it emits the command result on stdout — by default human-readable (via EmitText, formatted by the cli package), or, when the caller opts in with --json/--compact, exactly one JSON document (via EmitJSON, a json.RawMessage passthrough preserving the API's own field order). On failure it writes the error to stderr — a human-readable line by default, or the structured {"error": ...} object under --json — and owns the error -> exit-code map (the classification, and thus the exit code, is identical in both modes). This package stays generic: it knows JSON and raw text, never command-specific formatting.
Index ¶
Constants ¶
const ( ExitSuccess = 0 // success ExitInternal = 1 // network failure or internal error ExitUsage = 2 // usage error — the caller can fix the invocation ExitAPI = 3 // the Korbit API rejected the request (see error.code) ExitConfig = 4 // key/keystore/config problem — fix with `korbit key ...` )
Process exit codes. This taxonomy is a public contract agents branch on, so the values are stable — extend additively, never renumber. These are the only codes the CLI mints; a passthrough subprocess (e.g. the sandbox bundle) may forward its own arbitrary status verbatim. ExitCodes pairs each with its agent-facing description.
Variables ¶
var ExitCodes = map[string]string{ strconv.Itoa(ExitSuccess): "success", strconv.Itoa(ExitInternal): "network failure or internal error", strconv.Itoa(ExitUsage): "usage error — the command line is invalid (fix the invocation)", strconv.Itoa(ExitAPI): "the Korbit API rejected the request (see error.code)", strconv.Itoa(ExitConfig): "key or configuration problem — fix with `{prog} key ...` or config.json", }
ExitCodes documents every exit code, surfaced in help and the `commands` catalog so agents can map a non-zero status to a cause. Keyed by the decimal status (from the Exit* taxonomy, never a bare literal). The {prog} token is substituted with the program's invoked name by the render/catalog layer.
Functions ¶
This section is empty.
Types ¶
type ApiError ¶
type ApiError struct {
Message string
HTTPStatus int
Code string // symbolic code; "" when the body carried none
RetryAfterSec *int // set only when a Retry-After header was present
Body json.RawMessage // the raw error body, for diagnostics
// Guidance is CLI-added recovery advice attached on the error path when the
// symbolic code alone isn't enough to act safely — notably a duplicate place
// whose order can't be read back ("the order IS placed; do NOT re-place,
// fetch it"). It rides the error envelope (error.guidance) and the human
// error line so an agent reading stdout/JSON only never has to parse a
// free-floating stderr note. Empty for ordinary API rejections.
Guidance string
}
ApiError marks a request the Korbit API rejected (ExitAPI). Code is the symbolic error string (the envelope's error.message); HTTPStatus is the envelope's error.code.
type ConfigError ¶
ConfigError marks a key/keystore/config problem (ExitConfig). An optional Cause lets a ConfigError wrap a sentinel for errors.Is matching while keeping its own user-facing Message — used e.g. to mark "unknown keystore backend" apart from "backend unavailable" (both ConfigError, same exit code). Cause never changes Error()/ExitCode(), only what errors.Is/Unwrap see.
func Configf ¶
func Configf(format string, a ...any) *ConfigError
Configf builds a ConfigError from a format string.
func (*ConfigError) Error ¶
func (e *ConfigError) Error() string
func (*ConfigError) ExitCode ¶
func (e *ConfigError) ExitCode() int
func (*ConfigError) Unwrap ¶
func (e *ConfigError) Unwrap() error
type IO ¶
IO bundles the streams a command writes to, so the whole CLI can run in-process under test against buffers.
func (IO) EmitError ¶
EmitError classifies err and writes it to stderr — a human-readable line by default, or the structured {"error": ...} envelope when jsonMode is set (compact controls single-line vs pretty for the envelope) — then returns the process exit code. The classification, and thus the exit code, is identical in both modes; only the rendering differs.
func (IO) EmitJSON ¶
EmitJSON writes value as the single stdout document. A json.RawMessage is reproduced verbatim (preserving the API's own field order); any other value is marshalled without HTML escaping. compact selects single-line output.
func (IO) EmitText ¶
EmitText writes a block of human-readable text to stdout, followed by a single trailing newline. It is the stdout sink for the human-readable output mode; the text itself is formatted by the cli package, which knows the command. The wire (JSON) contract is unaffected — see EmitJSON.
type UsageError ¶
type UsageError struct{ Message string }
UsageError marks an invalid invocation the caller can fix.
func Usagef ¶
func Usagef(format string, a ...any) *UsageError
Usagef builds a UsageError from a format string.
func (*UsageError) Error ¶
func (e *UsageError) Error() string
func (*UsageError) ExitCode ¶
func (e *UsageError) ExitCode() int
Source Files