[master] 24964525a Add a JSON section to varnish-cli(7).

Geoff Simmons geoff at uplex.de
Mon Oct 8 11:28:13 UTC 2018

commit 24964525aba9f05245e80e4182236253d4019be3
Author: Geoff Simmons <geoff at uplex.de>
Date:   Tue Oct 2 14:12:02 2018 +0200

    Add a JSON section to varnish-cli(7).
    Closes #2783

diff --git a/doc/sphinx/reference/varnish-cli.rst b/doc/sphinx/reference/varnish-cli.rst
index 53387672a..38364cede 100644
--- a/doc/sphinx/reference/varnish-cli.rst
+++ b/doc/sphinx/reference/varnish-cli.rst
@@ -170,6 +170,38 @@ Other pitfalls include variable expansion of the shell invoking ``varnishadm``
 but this is not directly related to the Varnish CLI. If you get the quoting
 right you should be fine even with complex commands.
+A number of commands with informational responses support a ``-j`` parameter
+for JSON output, as specified below. The top-level structure of the JSON
+response is an array with these first three elements:
+* A version number for the JSON format (integer)
+* An array of strings that comprise the CLI command just received
+* The time at which the response was generated, as a Unix epoch time
+  in seconds with millisecond precision (floating point)
+The remaining elements of the array form the data that are specific to
+the CLI command, and their structure and content depend on the
+For example, the response to ``status -j`` just contains a string in
+the top-level array indicating the state of the child process
+(``"running"``, ``"stopped"`` and so forth)::
+  [ 2, ["status", "-j"], 1538031732.632, "running"
+  ]
+The JSON responses to other commands may have longer lists of
+elements, which may have simple data types or form structured objects.
+JSON output is only returned if command execution was successful. The
+output for an error response is always the same as it would have been
+for the command without the ``-j`` parameter.

More information about the varnish-commit mailing list