Skip to content

Run and chats

Run one prompt headless, and list, read, delete and search chats on this machine.

dexto run runs one prompt without a terminal. It prints JSON when stdout is not a terminal, and the reply at one. Approvals nobody can give are refused and listed as permission_denials. Its result and --stream-json events are described in Output and exit codes.

dexto run, dexto chat list|history|delete and dexto search do not use the shared contract options. The chat local and chat import commands, which read Claude Code and Codex chats, do. dexto chat import asks first unless you pass --yes.

Options before the command, such as --agent, --model and --auto-approve, apply to dexto run too. See The harness.

Generated from dexto 2.0.0-beta.0.

dexto run

Run a single prompt non-interactively (headless mode)

dexto run [prompt]

Examples

dexto run "summarize this repository"
echo "fix lint errors" | dexto run
dexto run - < prompt.txt
dexto run "list the TODOs" --stream-json
Option What it does
-m, --model <model> Specify the LLM model to use for this run
--json Print one JSON result (the default when stdout is not a terminal)
--stream-json Print JSON events, one per line, ending with one result
--text Print only the reply (the default at a terminal)

Approvals no one here can give are refused and listed in the result's permission_denials. Exit codes: 0 done, 1 failed, 2 usage, 3 needs sign-in or permission, 4 needs confirmation, 5 not found, 6 waiting on a person.

A local command: it does not follow the JSON and exit-code contract.

dexto chat list

List this machine's chats

dexto chat list

A local command: it does not follow the JSON and exit-code contract.

dexto chat history

Show a chat's messages

dexto chat history [sessionId]

A local command: it does not follow the JSON and exit-code contract.

dexto chat delete

Delete a chat

dexto chat delete <sessionId>

A local command: it does not follow the JSON and exit-code contract.

dexto chat local

List Claude Code or Codex chats on this machine, newest first, to pick some for chat import.

dexto chat local
Option What it does
--dir <dir> Read sessions from this folder (default: $CLAUDE_CONFIG_DIR/projects or ~/.claude/projects; $CODEX_HOME/sessions or ~/.codex/sessions).
--from <from> Where the chats are: claude-code or codex.
--folder <folder> Only sessions run in this folder or inside it, such as . for this repository.
--since <since> Only sessions with a turn on or after this date, such as 2026-10-01.

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

dexto chat import

Import Claude Code or Codex chats from this machine as your private Dexto chats, redacted here first.

dexto chat import [session_ids...]
Option What it does
--dir <dir> Read sessions from this folder (default: $CLAUDE_CONFIG_DIR/projects or ~/.claude/projects; $CODEX_HOME/sessions or ~/.codex/sessions).
--from <from> Where the chats are: claude-code or codex.
--folder <folder> Only sessions run in this folder or inside it, such as . for this repository.
--since <since> Only sessions with a turn on or after this date, such as 2026-10-01.
--all Import every session chat local lists.
--dry-run Send nothing; show what each import would send and what was redacted.
--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.

Search session history

dexto search <query>
Option What it does
--session <sessionId> Search in specific session
--role <role> Filter by role (user, assistant, system, tool)
--limit <number> Limit number of results (default: "10")

A local command: it does not follow the JSON and exit-code contract.

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.