> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/for-devops-and-administrators/automate/json-output.md). # Read results as JSON Get Devolutions CLI results as JSON or YAML, in one envelope for every command, so scripts can check success and errors reliably. The default text output is written for people: its layout differs from one command to the next and can change. For a script, ask for JSON or YAML. Every command then answers with the same envelope, for successes and for errors, so your script checks one field to know what happened. ## Choose the output format

OPTION	WHAT YOU GET
`--output text` (default)	Readable text, different for each command. Don't parse it.
`--output json` or `--json`	The JSON envelope, indented.
`--output yaml` or `--yaml`	The same envelope, in YAML.

These options work with every command. Use only one of them per command: `--json` with `--yaml`, or `--json` with `--output yaml`, stops the command with the error `conflictingOptions`. `--json` with `--output json` is accepted. ```bash devo vault list --json ``` ## The envelope ```json { "status": "success", "command": "vault.list", "operationId": null, "data": [ ], "warnings": [], "errors": [] } ```

FIELD	WHAT IT CONTAINS
`status`	`success`, `partial`, or `error`. Check this field first. `partial` means the command completed but some items failed: `data` holds what succeeded, `errors` lists what didn't, and the exit code is `0`.
`command`	The command that ran, as a dotted path such as `vault.list` or `entry.references`. Aliases and option values don't change it.
`operationId`	An identifier when the command produced one, otherwise `null`.
`data`	The result. Its shape depends on the command.
`warnings`	Notices that didn't stop the command.
`errors`	One item per error. Empty when `status` is `success`; not empty when it's `partial` or `error`.

Each item in `errors` has these fields:

FIELD	WHAT IT CONTAINS
`code`	A stable error code, such as `missingParameter` or `conflictingOptions`. Base your script's decisions on this field.
`message`	An explanation for people. Its wording can change, so don't match on it.
`target`	The option, argument, or resource the error is about, when known.
`blockerStatus`, `stageStatuses`	Details from the workspace runtime, when the error comes from it.

A command line that Devolutions CLI can't parse, such as a misspelled command, also returns the envelope, with errors coded `usageError`, and sometimes a `usageSuggestion` item that proposes the right spelling. ## Use it in a script Check the exit code first, then read the envelope. A `partial` result exits with `0`, so also report `errors` when the exit code is `0`. For example, with `jq`: {% tabs %} {% tab title="Bash" %} ```bash if result=$(devo vault list --json); then echo "$result" | jq -r '.data[].name' # A partial result exits with 0 and still lists errors. echo "$result" | jq -r '.errors[] | "\(.code): \(.message)"' >&2 else echo "$result" | jq -r '.errors[] | "\(.code): \(.message)"' >&2 exit 1 fi ``` {% endtab %} {% tab title="PowerShell" %} ```powershell $result = devo vault list --json | ConvertFrom-Json # 'partial' and 'error' both list their errors. $result.errors | ForEach-Object { Write-Warning "$($_.code): $($_.message)" } if ($result.status -eq 'error') { exit 1 } # 'success' or 'partial': data holds what succeeded. $result.data | ForEach-Object { $_.name } ``` {% endtab %} {% endtabs %} The exit codes are listed in [Exit codes and errors](/cli/reference/exit-codes-and-errors.md). ## Standard output and standard error

STREAM	WHAT GOES THERE
Standard output	The envelope, in JSON or YAML, for successes and errors. In text, the result. In text, errors from `devo login` and from commands available only on Devolutions Cloud or only on Devolutions Server also go here, as `<code>: <message>`.
Standard error	In text, most errors, as `<code>: <message>`. Notices about what Devolutions CLI is doing, such as `Starting Devolutions CLI daemon...`, and the prompts and messages of interactive sign-in.

So in JSON or YAML, read standard output only: it contains exactly one envelope. The exception is `devo secret run`, described below. ## Quiet or verbose Notices about what Devolutions CLI is doing, such as starting the background process, are written to standard error: * In text output, they appear by default. `--quiet` hides them. * In JSON or YAML output, they're hidden by default. `--verbose` shows them, still on standard error. `--quiet` and `--verbose` together stop the command with `conflictingOptions`. ## Good to know * `devo secret run` doesn't wrap the output of the program it starts: the program's output goes to your terminal as the program writes it, with secret values masked. How its own errors come back depends on when they happen: * A launch Devolutions CLI rejects before resolving anything, such as a reference in the command's arguments (`secretLaunchArgumentReference`), a failed `--check`, or a program that can't start, returns the envelope on standard output with `--json` or `--yaml`. * A reference that doesn't resolve is always written to standard error as `

: `, even with `--json`, and the program doesn't start.
  * A program stopped by `--timeout-seconds` exits with `124`; an interrupted run exits with `130`.
  * Otherwise, `devo secret run` returns the program's own exit code. See [Exit codes and errors](/cli/reference/exit-codes-and-errors.md).
* Every command and its options are in [Commands](/cli/reference/commands.md).

## Next

* [Run without prompts](/cli/for-devops-and-administrators/automate/non-interactive.md)
* [Exit codes and errors](/cli/reference/exit-codes-and-errors.md)
* [Global options](/cli/reference/global-options.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/cli/for-devops-and-administrators/automate/json-output.md?ask=&goal=
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.