Skip to content

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.

stdout is…The command prints
a terminaltables and text for you
a pipe or a fileJSON

Choose either way with a flag on any of these commands:

  • --json prints JSON even at a terminal. It also prints failures as JSON.
  • --table prints 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:

Terminal window
dexto cloud agents list --limit 50 --after "$NEXT"

Stop when has_more is false. A short list prints {"data": []} rather than failing.

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"
}
}
FieldMeaning
codeA short stable name, such as needs_sign_in, needs_permission, not_found
messageWhat happened, for a person
fixThe command or action that fixes it, when there is one. Run it, then retry
api_codeThe Dexto API’s own error code, when the API refused the request
detailsExtra structure, such as which field was invalid

Branch on the exit code first, then on code. Do not match on message.

Every command that follows the contract exits with one of these:

CodeMeaningWhat to do
0DoneRead stdout
1FailedRead error.message; retry only if it says so
2Usage or invalid inputFix the arguments; the message says which
3Needs sign-in or permissionRun fix; see Sign in
4Needs confirmationAsk your person, then repeat the command with --yes
5Not foundThe id, name or path does not exist in this project
6Waiting on a person, such as an approvalStop 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).

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.

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.

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 runs one prompt headless and has its own formats:

FlagPrints
--textOnly the reply. The default at a terminal
--jsonOne JSON result. The default when stdout is not a terminal
--stream-jsonOne 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.

Terminal window
dexto run "summarize this repository" | jq -r .content
echo "fix the lint errors" | dexto run --stream-json
dexto run - < prompt.txt
Terminal window
dexto --help --json # every command, with its own help command, and the exit codes
dexto cloud agents list --help --json # one command's options and usage

dexto --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.