Skip to content

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.

Node.js 20, 22 or 24 works; 22 is recommended. Use npm. Install once:

Terminal window
npm install -g dexto

If 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:

Terminal window
dexto whoami --json

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

Terminal window
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 --json to be sure.
  • Lists print {"data": [...], "has_more": …, "next_after": …}. Pass next_after back as --after.
  • Notices and progress go to stderr, so stdout is always parseable.
  • Use --project <project> or DEXTO_CLOUD_PROJECT for the Cloud project, and --profile or DEXTO_PROFILE for 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.

CodeMeaningYou should
0DoneRead stdout
1FailedRead error.message
2Invalid inputFix the arguments
3Needs sign-in or permissionRun error.fix
4Needs confirmationAsk your person; then repeat with --yes
5Not foundCheck the id or name
6Waiting on a personStop 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 --yes on your own. Exit 4 means a person has to agree first. Tell them what the command does, and repeat it with --yes only after they say yes.
  • Do not read or print secrets. Pass a secret on stdin or in an environment variable. dexto cloud secrets never shows values.
  • Keep one Cloud project in mind. A command acts in one project; check dexto whoami if a result looks wrong.
  • Do not parse tables. They are for people; use JSON.
Terminal window
dexto run "summarize this repository" # JSON when piped
echo "fix the lint errors" | dexto run --stream-json # events, then one result

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