> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dwolla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dwolla CLI

> Explore the Dwolla API, seed sandbox data, and automate webhook workflows from your terminal and AI coding agents with the official Dwolla command-line interface.

The Dwolla CLI is the official command-line interface for the Dwolla API. Use it to explore any API resource as a command, seed sandbox data with built-in workflows, fire real sandbox webhook events, and receive webhooks locally over a public tunnel, all from your terminal. It also detects when it is running inside an AI coding agent and adapts its output, so agents can drive it directly.

<Note>
  The Dwolla CLI is in **public beta**. Commands and flags are stable but may still change ahead of the `v1` release.
</Note>

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/dwolla/dwolla-cli">
    View the full README, report issues, and explore the source code on GitHub.
  </Card>

  <Card title="Releases" icon="download" href="https://github.com/dwolla/dwolla-cli/releases">
    Download pre-built binaries for macOS, Linux, and Windows.
  </Card>
</CardGroup>

## Installation

The quickest way to install is the one-line script for your platform. If you already have Go installed, you can install from source instead.

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={"dark"}
    curl -fsSL https://raw.githubusercontent.com/dwolla/dwolla-cli/v0.1.0-beta.1/scripts/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    Run the following in PowerShell:

    ```powershell theme={"dark"}
    irm https://raw.githubusercontent.com/dwolla/dwolla-cli/v0.1.0-beta.1/scripts/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={"dark"}
    go install github.com/dwolla/dwolla-cli/cmd/dwolla@latest
    ```

    Requires Go 1.25 or later.
  </Tab>

  <Tab title="Manual">
    Download the archive for your platform from [GitHub Releases](https://github.com/dwolla/dwolla-cli/releases) and extract the `dwolla` binary onto your `PATH`.

    <Note>
      The binary is not yet code-signed and notarized, so macOS Gatekeeper blocks binaries downloaded through a browser. Clear the quarantine attribute once before running it:

      ```bash theme={"dark"}
      xattr -d com.apple.quarantine ./dwolla
      ```

      This step does not apply to the install script above, since files fetched by `curl` are not quarantined.
    </Note>
  </Tab>
</Tabs>

<Note>
  Both install scripts verify the download's SHA-256 checksum against the published `checksums.txt` and abort if it does not match. Set `DWOLLA_VERSION` to install a specific version, or `DWOLLA_INSTALL_DIR` to choose where the binary lands.
</Note>

Verify the install by running `dwolla --help`.

## Quick tour

These commands take you from setting credentials through a full `send-money` scenario in the sandbox.

Before you start, you need a Dwolla Sandbox account and an application's key and secret. [Create a sandbox account](https://accounts-sandbox.dwolla.com/sign-up), then copy the key and secret from the [Applications page](https://dashboard-sandbox.dwolla.com/applications). Set your credentials, then run each command in order.

```bash theme={"dark"}
# Set your sandbox application credentials
export DWOLLA_CLIENT_ID=YOUR_SANDBOX_CLIENT_ID
export DWOLLA_CLIENT_SECRET=YOUR_SANDBOX_CLIENT_SECRET
export DWOLLA_TOKEN_URL=https://api-sandbox.dwolla.com/token

# Or store your credentials in the OS keychain instead of exporting them:
# dwolla auth login

dwolla auth whoami               # confirm your credentials and environment
dwolla root get                  # fetch your account root
dwolla workflows run send-money  # run an end-to-end sandbox scenario
```

To fire webhook events and receive them locally, see [Seed and automate](#seed-and-automate) and [Receive webhooks locally](#receive-webhooks-locally) below.

<Tip>
  We recommend storing your credentials in the OS keychain with `dwolla auth login` rather than exporting them, since the keychain keeps the secret out of your shell history and off disk in plaintext. Environment variables are fine for a quick sandbox run or CI. The CLI resolves credentials in priority order: command flag, environment variable, OS keychain, then config file.
</Tip>

## Core capabilities

Most Dwolla integrations follow the same arc in the sandbox: inspect a few endpoints to learn the shape of their responses, create the customers, funding sources, and transfers your scenario needs, then confirm your app handles the webhooks those actions produce. The CLI covers all three steps from your terminal, handling token exchange, HAL link traversal, and resource IDs on your behalf.

Each section below covers one of those steps, in that order. All of the commands shown assume the sandbox credentials from the [quick tour](#quick-tour).

### Explore the API

Every Dwolla API resource maps to a command group, so you can call the API without writing code. Each command supports five output formats through `--output-format` (`-o`): `pretty` (the default), `json`, `yaml`, `table`, and `toon`. You can also filter results inline with a jq expression using `--jq` (`-q`).

```bash theme={"dark"}
dwolla customers list                          # list customers
dwolla transfers get --transfer-id <id>        # fetch a specific transfer
dwolla customers list -o json --jq '.[].id'    # filter output with jq
```

To browse the available commands interactively without memorizing syntax, run `dwolla explore`. The [command reference](https://github.com/dwolla/dwolla-cli/blob/main/docs/commands.md) covers every command group and flag.

### Seed and automate

Workflows run multi-step sandbox scenarios with a single command, chaining resource IDs and HAL links between steps for you. Nine built-in workflows cover common flows: `send-money`, `receive-money`, `me-to-me`, `facilitate-payment`, the four `onboard-*` scenarios, and `seed-sandbox`. Each takes flags to branch the scenario, such as customer type, rail, and amount. You can also author your own as a JSON file and run it with `dwolla workflows run ./my-workflow.json`.

```bash theme={"dark"}
dwolla workflows list                        # list built-in workflows
dwolla workflows list --slug send-money      # show the flags for one workflow
dwolla workflows run send-money              # run an end-to-end scenario
dwolla workflows run send-money --dry-run    # preview the step plan without calling the API
```

See the [workflows guide](https://github.com/dwolla/dwolla-cli/blob/main/docs/workflows.md) for the full catalog, the flag matrix for each workflow, and the custom workflow JSON format.

<Warning>
  Workflows are **sandbox-only**, built-in and custom alike. A run against production credentials is refused before any step executes, so a workflow can never apply part of a scenario and then stop. `--dry-run` still previews the step plan in any environment.
</Warning>

Triggers create the resources needed to fire a real sandbox webhook event in one command, so you can test webhook handlers without setting them up by hand.

```bash theme={"dark"}
dwolla trigger --list                # see available events
dwolla trigger transfer_completed    # create resources and fire the event
```

### Receive webhooks locally

The `listen` command opens a public tunnel, registers a Dwolla webhook subscription that points at it, and forwards incoming events to your local app, prints them to your terminal, or both. Each delivery is verified against its signature, and the subscription is removed automatically when you exit.

```bash theme={"dark"}
dwolla listen --print                              # print payloads to stdout
dwolla listen --forward-to localhost:3000/webhooks # forward to your local app
```

Use `--events` to filter to specific topics. Tunnels run through Cloudflare Quick Tunnels when `cloudflared` is on your `PATH`, falling back to localtunnel otherwise; `--tunnel` forces a specific backend.

Pair `listen` with `trigger` in two terminals to watch an event flow end to end. Start `dwolla listen --print` in one, then run `dwolla trigger transfer_completed` in the other.

## Environments and access

The CLI defaults to the **sandbox** environment. Set `DWOLLA_ENV=production` or a production token URL to target production.

<Warning>
  Production access is **read-only**. The CLI refuses any mutating command run against production credentials, so production is meant for debugging with reads such as `dwolla root get` or `dwolla events list`. The `trigger`, `listen`, and `workflows run` commands are sandbox-only and refuse to run against production at all.
</Warning>

## Learn more

* [Command reference](https://github.com/dwolla/dwolla-cli/blob/main/docs/commands.md) covers every command and flag.
* [Workflows guide](https://github.com/dwolla/dwolla-cli/blob/main/docs/workflows.md) explains the built-in catalog, flag matrices, and the custom workflow JSON format.
* [Agent mode](https://github.com/dwolla/dwolla-cli/blob/main/docs/agent-mode.md) describes how the CLI adapts when it detects an AI coding agent such as Claude Code, Cursor, or Codex: token-efficient TOON output, structured JSON errors with recovery hints, and no interactive prompts.
* [GitHub repository](https://github.com/dwolla/dwolla-cli) has the source code, releases, and issues.