From 12f17c0075a86a8423ec17f57e8ae8decf0d7ac3 Mon Sep 17 00:00:00 2001
From: Pim van Pelt <pim@ipng.ch>
Date: Fri, 5 Jun 2026 23:43:17 +0200
Subject: [PATCH] docs(maglevc): document -json; verified live against maglevd
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add the -json flag to maglevc(1): the contract verified by a live smoke
test against a maglevd (chbtl2) — show/query commands print the object
as JSON, actions (set/sync/config reload) print {} on success, and
failures print {"error": "..."} on stderr with a non-zero exit. JSON
output is never colorized. Also corrects the -color description (the
palette is now bright blue, shared from golang-cli) and refreshes the
man date.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/maglevc.1 | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/docs/maglevc.1 b/docs/maglevc.1
index 40b590b..6ba7285 100644
--- a/docs/maglevc.1
+++ b/docs/maglevc.1
@@ -1,10 +1,11 @@
-.TH MAGLEVC 1 "April 2026" "vpp\-maglev" "User Commands"
+.TH MAGLEVC 1 "June 2026" "vpp\-maglev" "User Commands"
 .SH NAME
 maglevc \- Maglev health\-checker CLI client
 .SH SYNOPSIS
 .B maglevc
 [\fB\-server\fR \fIaddr\fR]
 [\fB\-color\fR[=\fIbool\fR]]
+[\fB\-json\fR]
 [\fIcommand\fR [\fIargs\fR...]]
 .SH DESCRIPTION
 .B maglevc
@@ -38,7 +39,7 @@ gRPC server.
 .RI "(default: " localhost:9090 "; env: " MAGLEV_SERVER )
 .TP
 .BR \-color [=\fIbool\fR]
-Colorize static field labels in output using ANSI dark blue. The
+Colorize static field labels in output using ANSI blue. The
 default is mode\-aware: enabled (true) in the interactive shell, and
 disabled (false) in one\-shot mode so that output piped into scripts
 or files stays free of escape codes. Pass
@@ -47,6 +48,18 @@ or
 .B \-color=false
 explicitly to override the default for either mode.
 .TP
+.B \-json
+Emit JSON instead of human\-readable text, for scripting. Every
+.B show
+or query command prints the underlying object as JSON; an action that
+changes state
+.RB ( set ", " sync ", " "config reload" )
+prints
+.B {}
+on success; and any failure prints
+.B {\(dqerror\(dq: \(dq...\(dq}
+on stderr with a non\-zero exit status. JSON output is never colorized.
+.TP
 .B \-version
 Print version, commit hash, and build date, then exit.
 .SH EXAMPLES
@@ -84,6 +97,20 @@ Query VPP version and connection status, forcing color on:
 $ maglevc \-color=true show vpp info
 .EE
 .RE
+.PP
+Emit JSON for scripting. A query returns the object; an action returns
+.BR {} ;
+a failure returns
+.B {"error": ...}
+with a non\-zero exit status:
+.PP
+.RS
+.EX
+$ maglevc \-json show frontend nginx\-ip4\-http
+$ maglevc \-json sync vpp lb state
+{}
+.EE
+.RE
 .SH "FULL DOCUMENTATION"
 This manpage documents only the invocation of
 .BR maglevc .