Dexto CLI for agents
The short version for an agent driving the Dexto CLI. Install, sign in, run commands, read results, and recover from errors.Read this first if you are an agent. Everything here is covered in more detail on the other CLI pages, which this page links.
Install
Section titled “Install”Node.js 20, 22 or 24 works; 22 is recommended. Use npm. Install once:
npm install -g dextoIf npm fails with EACCES, don’t use sudo; use the install script
(installs under ~/.dexto, no admin).
dexto login --device prints a link and code on stderr, then waits for approval. Run it so you
can read its output while it waits, and pass both to the person.
Do not approve sign-in on their behalf. Check the first account result:
dexto whoami --jsonSuccess is exit 0 with your account identity. Signed-out account commands exit 3 with
needs_sign_in; for a headless machine, run dexto login --device and retry. Installation and
dexto --version need no sign-in. Account and workspace requests do; model runs also need a
configured model or credits. This check starts no model run.
See Sign in for profiles and project API keys. Workspace commands use OAuth.
Run commands
Section titled “Run commands”dexto cloud agents list | jq '.data[].id'dexto cloud agents get "$AGENT"dexto cloud files upload ./report.pdf- stdout is JSON when it is not a terminal. Add
--jsonto be sure. - Lists print
{"data": [...], "has_more": …, "next_after": …}. Passnext_afterback as--after. - Notices and progress go to stderr, so stdout is always parseable.
- Use
--project <project>orDEXTO_CLOUD_PROJECTfor the Cloud project, and--profileorDEXTO_PROFILEfor the account. Do not rely on a saved “current” choice you did not make.
To find a command: dexto --help --json lists them all, dexto <command> --help --json prints one
command’s options, and dexto find "what you want to do" searches Dexto’s operations. The
command reference lists everything.
Read the exit code
Section titled “Read the exit code”| Code | Meaning | You should |
|---|---|---|
| 0 | Done | Read stdout |
| 1 | Failed | Read error.message |
| 2 | Invalid input | Fix the arguments |
| 3 | Needs sign-in or permission | Run error.fix |
| 4 | Needs confirmation | Ask your person; then repeat with --yes |
| 5 | Not found | Check the id or name |
| 6 | Waiting on a person | Stop and tell your person |
Errors are on stderr as {"error":{"code","message","fix"}}. Branch on the exit code, then
error.code; never on message. See Output and exit codes.
- Never pass
--yeson your own. Exit 4 means a person has to agree first. Tell them what the command does, and repeat it with--yesonly after they say yes. - Do not read or print secrets. Pass a secret on stdin or in an environment variable.
dexto cloud secretsnever shows values. - Keep one Cloud project in mind. A command acts in one project; check
dexto whoamiif a result looks wrong. - Do not parse tables. They are for people; use JSON.
Run an agent headless
Section titled “Run an agent headless”dexto run "summarize this repository" # JSON when pipedecho "fix the lint errors" | dexto run --stream-json # events, then one resultdexto run refuses approvals nobody can give and lists them in permission_denials in the result.
Check that list before you rely on the output. See dexto run.