Merge pull request #1230 from bbassie/feature/ctl-output-json

Add --output json to clusterioctl
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-11-20 15:22:38 +00:00
commit 34deacb881
26 files changed
+1048 -347

No files matched your search

+18
View File
@@ -8,6 +8,24 @@ Before `clusterioctl` can be used it needs to be configured for the cluster it w
The easiest way to do this is to run `npx clusteriocontroller bootstrap create-ctl-config <username>` on the controller, which creates the necessary `config-ctl.json` for managing the cluster as the given user.
## Output Format
ctl> --output json <command>
Print the result of the command as JSON on stdout instead of text meant for reading.
Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`.
If the command fails it prints `{"error": "<ClassName>", "message": "<message>"}` and exits with a non-zero exit code.
Log messages are written to stderr in all formats.
`--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`.
The `json` format uses the property names shown in the tables of the human format.
`log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive.
`instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop.
The default is `--output human`, which prints `Command ran successfully` for commands that have no result.
## Hosts
### List hosts
+14
View File
@@ -995,6 +995,20 @@ For a command the `definition` is the arguments to pass to [yargs.command](http:
The `handler` is an async function that's invoked when the command is executed and it's passed the parsed command line arguments and a reference to the `Ctl` class of clusterioctl.
Note that messages sent from clusterioctl needs to have `"control"` as a part of `src` for it to be accepted by the controller, see [Defining Link Messages](#defining-link-messages) for how to define the messages that can be sent to the controller.
Commands print their results through `ctl.output` so that `--output json` works for them:
```js
handler: async function(args, ctl) {
const result = await ctl.sendTo("controller", new messages.FrobnicateRequest(args.type));
ctl.output.result(result, () => console.log(`Frobnicated ${result.count} foos`));
},
```
`ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise.
`ctl.output.table(rows, map)` prints an array of objects as a JSON array, or as a table in human mode with `map` applied to each row first.
`ctl.output.human` is true when the output is meant for reading.
Commands that print nothing get `Command ran successfully` or `{"success": true}` printed for them, and errors thrown from the handler are printed as `{"error": "<ClassName>", "message": "<message>"}` in json and wire mode.
To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in the `addCommands` hook of the ctl entrypoint:
```js