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.
dexto cloud agents chat "$AGENT" "check the build" --jsondexto 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. |