Skip to content

Cloud agents

Create and update Dexto Cloud agents, chat with them, approve their tool calls, and read their sessions and runs.

These commands follow the output contract: JSON when stdout is not a terminal, failures as JSON on stderr, and exit codes 0 to 6.

Terminal window
dexto cloud agents chat "$AGENT" "check the build" --json
dexto cloud agents sessions list "$AGENT"
dexto cloud agents runs steps "$AGENT" "$SESSION" "$RUN"

A run can wait on a tool call that needs a person. approve and reject answer it. Commands that end something, such as archive and sessions delete, exit 4 until you pass --yes; ask your person first.

Generated from dexto 2.0.0-beta.0.

dexto cloud agents list

List the project's agents.

dexto cloud agents list
Option What it does
--after <after> Start after this cursor, from the previous page.
--limit <limit> How many to return.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents get

Show an agent's current version.

dexto cloud agents get <agent_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents create

Create an agent from flags, or from a full definition with --file or --data.

dexto cloud agents create
Option What it does
--data <data> The request body as JSON.
--file <file> Read the request body from a JSON file, or - for stdin.
--description <description> A description for your reference.
--instructions <instructions> The agent's system instructions.
--model <model> A model id from dexto cloud models list.
--name <name> Display name.
--tool <tool> … Add a tool: automations, files, media, sandbox, web_fetch, web_search. Others need --file.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents update

Change an agent: flags change those fields, --file replaces the whole definition.

dexto cloud agents update <agent_id>
Option What it does
--data <data> The request body as JSON.
--file <file> Read the request body from a JSON file, or - for stdin.
--description <description> A description for your reference.
--instructions <instructions> The agent's system instructions.
--model <model> A model id from dexto cloud models list.
--name <name> Display name.
--tool <tool> … Add a tool: automations, files, media, sandbox, web_fetch, web_search. Others need --file.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents archive

Archive an agent: it accepts no new runs and its session sandboxes end.

dexto cloud agents archive <agent_id>
Option What it does
--yes Go ahead without being asked. Pass it only once your person has agreed.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents chat

Send a message and stream the reply. Without a message at a terminal, keeps chatting until an empty line.

dexto cloud agents chat <agent_id> [message...]
Option What it does
--session <session> Continue this session instead of starting one.
--user <user> The end-user label for a new session (default cli).
--yes Approve every tool call the agent asks to make.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents approve

Approve a tool call a run is waiting on.

dexto cloud agents approve <agent_id> <session_id> <approval_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents reject

Reject a tool call a run is waiting on.

dexto cloud agents reject <agent_id> <session_id> <approval_id>
Option What it does
--message <message> Why, for the agent.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents sessions list

List an agent's sessions.

dexto cloud agents sessions list <agent_id>
Option What it does
--after <after> Start after this cursor, from the previous page.
--limit <limit> How many to return.
--user <user> Only this end user's sessions.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents sessions get

Show a session and its active run.

dexto cloud agents sessions get <agent_id> <session_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents sessions delete

Delete a session with its messages, runs and stored tool output.

dexto cloud agents sessions delete <agent_id> <session_id>
Option What it does
--yes Go ahead without being asked. Pass it only once your person has agreed.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents sessions cancel

Cancel the session's active run.

dexto cloud agents sessions cancel <agent_id> <session_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents messages

Read a session's messages, oldest first.

dexto cloud agents messages <agent_id> <session_id>
Option What it does
--after <after> Start after this cursor, from the previous page.
--limit <limit> How many to return.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents runs list

List a session's runs, newest first.

dexto cloud agents runs list <agent_id> <session_id>
Option What it does
--after <after> Start after this cursor, from the previous page.
--limit <limit> How many to return.

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents runs get

Show a run: its status, why it stopped and what it used.

dexto cloud agents runs get <agent_id> <session_id> <run_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

dexto cloud agents runs steps

List what a run did: each model turn and tool call.

dexto cloud agents runs steps <agent_id> <session_id> <run_id>

JSON when stdout is not a terminal, failures as JSON on stderr, exit codes 0 to 6. Also takes the shared options below.

Shared options

Commands on this page that follow the JSON contract take these.

Option What it does
--api-base-url <api-base-url> The API origin (default https://api.dexto.ai, or DEXTO_API_BASE_URL).
--api-key <api-key> Use this key instead of DEXTO_API_KEY or the saved sign-in.
--profile <profile> The saved sign-in to use for this run (or DEXTO_PROFILE); see dexto accounts list.
--project <project> The Cloud project to act in when you're signed in (or DEXTO_CLOUD_PROJECT).
--json Print JSON, failures included (on stderr). The default when stdout isn't a terminal.
--table Print tables for people even when stdout isn't a terminal.