Output and exit codes
How Dexto CLI commands print JSON, report errors, page through lists, and exit, so a script or an agent can rely on them.Most commands that talk to Dexto follow one contract, so you can write a script or an agent once and
use it with all of them. Those commands are login, logout, whoami, accounts, models list,
billing, find, publish, profile, skills push, workspace and everything under dexto cloud.
The command reference marks them. dexto run has its own JSON result,
described below.
JSON by default when nobody is watching
Section titled “JSON by default when nobody is watching”| stdout is… | The command prints |
|---|---|
| a terminal | tables and text for you |
| a pipe or a file | JSON |
Choose either way with a flag on any of these commands:
--jsonprints JSON even at a terminal. It also prints failures as JSON.--tableprints tables even when stdout is not a terminal.
A command that returns one thing prints that object. A command that returns a list prints:
{ "data": [{ "id": "…", "name": "…" }], "has_more": true, "next_after": "cursor_…"}Keys are snake_case. Pass next_after back as --after to read the next page, and --limit to
change the page size:
dexto cloud agents list --limit 50 --after "$NEXT"Stop when has_more is false. A short list prints {"data": []} rather than failing.
Errors
Section titled “Errors”A failure prints this on stderr, nothing on stdout, and exits non-zero:
{ "error": { "code": "needs_confirmation", "message": "Archiving agent x stops its new runs and ends its session sandboxes. Run it again with --yes once your person has agreed.", "fix": "dexto cloud agents archive x --yes" }}| Field | Meaning |
|---|---|
code | A short stable name, such as needs_sign_in, needs_permission, not_found |
message | What happened, for a person |
fix | The command or action that fixes it, when there is one. Run it, then retry |
api_code | The Dexto API’s own error code, when the API refused the request |
details | Extra structure, such as which field was invalid |
Branch on the exit code first, then on code. Do not match on message.
Exit codes
Section titled “Exit codes”Every command that follows the contract exits with one of these:
| Code | Meaning | What to do |
|---|---|---|
| 0 | Done | Read stdout |
| 1 | Failed | Read error.message; retry only if it says so |
| 2 | Usage or invalid input | Fix the arguments; the message says which |
| 3 | Needs sign-in or permission | Run fix; see Sign in |
| 4 | Needs confirmation | Ask your person, then repeat the command with --yes |
| 5 | Not found | The id, name or path does not exist in this project |
| 6 | Waiting on a person, such as an approval | Stop and tell your person |
dexto cloud sandboxes exec exits with the exit code of the command it ran. When the CLI itself
fails, the error object is on stderr.
An HTTP failure from the Dexto API maps to a code: 401 is needs_sign_in (exit 3), 403 is
needs_permission (exit 3), 404 is not_found (exit 5), and 400, 413 and 422 are invalid input
(exit 2).
Confirmation: --yes
Section titled “Confirmation: --yes”A command that deletes data, spends credits or can’t be undone does not run until you pass --yes.
Without a terminal it exits 4 and prints the exact command to repeat in fix. At a terminal it asks
you instead. --yes is for after a person has agreed, so an agent should ask first.
Notices go to stderr
Section titled “Notices go to stderr”Update notices, startup banners and progress go to stderr, so stdout carries only a command’s output
and dexto … | jq always works. Do not parse stderr except for the error object.
Shared options
Section titled “Shared options”Every command that follows the contract takes the same options. They are listed once, under
Shared options: --json, --table, --profile, --project,
--api-key and --api-base-url.
dexto run
Section titled “dexto run”dexto run runs one prompt headless and has its own formats:
| Flag | Prints |
|---|---|
--text | Only the reply. The default at a terminal |
--json | One JSON result. The default when stdout is not a terminal |
--stream-json | One JSON event per line, ending with the same result |
The result:
{ "type": "result", "status": "completed", "session_id": "…", "content": "The reply.", "total_tokens": 1234, "permission_denials": []}status is completed or failed; a failure also carries error with code usage or failed,
and prints the error object on stderr. Approvals nobody there can give are refused, the run goes on
without them, and each is listed in permission_denials with its approval_type, tool_name and
message. An empty prompt exits 2. With --stream-json the events are message_delta, tool_call,
tool_result, approval_required, response, warning and run_error.
dexto run "summarize this repository" | jq -r .contentecho "fix the lint errors" | dexto run --stream-jsondexto run - < prompt.txtDiscovering commands
Section titled “Discovering commands”dexto --help --json # every command, with its own help command, and the exit codesdexto cloud agents list --help --json # one command's options and usagedexto --help --json lists each command with the command that prints its help. A command that follows
the contract prints its help as JSON; the others print text.