Skip to content

agent-mode.md

Latest commit

 

History

History
110 lines (88 loc) · 3.59 KB

agent-mode.md

File metadata and controls

110 lines (88 loc) · 3.59 KB
Raw

Agent mode

The Dwolla CLI is built to be driven by AI coding agents as well as humans. When it detects that it's running inside an agent, it switches to agent mode: token-efficient structured output, machine-readable errors with recovery hints, and no interactive prompts.

How it's enabled

Agent mode turns on automatically when any of these environment variables is set to a truthy value (1, true, or yes):

Env var Agent
CLAUDE_CODE Claude Code
CURSOR_AGENT Cursor
CODEX OpenAI Codex
AIDER Aider
CLINE Cline
WINDSURF_AGENT Windsurf
GITHUB_COPILOT GitHub Copilot
AMAZON_Q Amazon Q
GEMINI_CODE_ASSIST Gemini Code Assist
SRC_CODY Sourcegraph Cody
FORCE_AGENT_MODE Force it on in any environment

You can also control it explicitly with the global --agent-mode flag, which overrides auto-detection:

FORCE_AGENT_MODE=1 dwolla customers list        # force on
CLAUDE_CODE=1 dwolla customers list --agent-mode=false   # force off despite detection

What changes in agent mode

  1. Default output becomes TOON. Without an explicit --output-format, agent mode emits TOON — a compact, token-efficient structured format. Override per-command with -o json, -o yaml, etc.
  2. Errors become structured JSON on stderr with a machine-readable type and recovery hints (see below).
  3. Interactive features are disabled. No auto-prompting, no explorer auto-launch, no TUI forms — the same as passing --no-interactive.
  4. No color codes are emitted, so output stays clean when captured.

TOON output

TOON (Token-Oriented Object Notation) encodes the same data as JSON in fewer tokens. Example:

CLAUDE_CODE=1 dwolla workflows list

To get plain JSON instead — for piping into jq or a parser — request it explicitly:

CLAUDE_CODE=1 dwolla workflows list -o json --jq '.[].name'

Structured errors

In agent mode, failures are printed once to stderr as a JSON envelope and the process exits non-zero. The envelope always includes an error_type and message, and usually hints — concrete next actions an agent can take.

{
  "error": "authentication failed (401)",
  "error_type": "authentication_error",
  "message": "authentication failed (401)",
  "hints": [
    "Set credentials via environment variables or CLI flags",
    "Run 'dwolla whoami' to check current authentication status"
  ]
}

Error types map from the HTTP status of the failed call:

error_type Cause
authentication_error 401
authorization_error 403
not_found 404
validation_error 400 / 422
rate_limit_error 429
server_error 5xx
connection_error network failure (status 0)
api_error any other non-2xx

Recommended agent patterns

  • Prefer JSON + --jq when you need to extract a specific value: dwolla customers list -o json --jq '.[0].id'.
  • Use --dry-run to preview a mutating request (including workflow step plans) before executing it — the hints for 422/400 errors suggest this.
  • Use dwolla whoami to confirm which credentials and environment are active before running commands.
  • Paginate lists with --limit and --offset (e.g. dwolla events list --limit 25 --offset 0) and extract fields with -o json --jq rather than parsing pretty output.

Related