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

# Use the CLI with coding agents

> Discover commands, inspect context, preview requests, and consume machine-readable results.

Give your agent the installed CLI and [configured credentials and context](/developer-tools/cli/auth-context). Use runtime discovery to plan each task against the commands that version supports.

## Discover and inspect a command

Read the command description and find a payment workflow:

```bash theme={null}
straddle agent-context --pretty
straddle which "reconcile funding" --json
straddle reconcile --help
```

`agent-context` includes `schema_version`, command names and flags, authentication requirements, and `runtime_context`. It reports the selected environment and account without opening the local store. `which` searches the built-in workflow descriptions; use resource help, such as `straddle charges --help`, for API operations.

## Choose an output mode

Choose the following mode for your caller:

| Caller | Option | Behavior |
| - | - | - |
| Terminal user | Default | Readable resource tables or detail output. |
| Terminal user who wants rich formatting | `--human-friendly` | Enables rich terminal formatting and color. |
| Script that needs JSON | `--json` | Selects JSON without changing confirmation defaults. |
| Coding agent | `--agent` | Defaults to `--json --compact --no-input --no-color --yes`. |

Piped or redirected resource output uses JSON unless another supported output format is selected. Piping doesn't enable the other `--agent` defaults. `--human-friendly` keeps piped resource output in JSON.

Explicit flags override agent defaults. To keep full resource fields, use `--agent --compact=false`. To request a smaller set of fields:

```bash theme={null}
straddle payments --agent --select id,status,amount
```

`--select` applies to resource fields, not envelope paths such as `meta.source`. Streaming commands have their own output shape: `sync`, for example, emits one JSON event per line.

## Preview a request before sending it

Before a write, check the effective environment and acting account with `agent-context`, inspect the operation's help, and prepare the request body. For a charge body saved as `charge.json`:

```bash theme={null}
straddle charges create --help
straddle charges create --stdin --dry-run --agent < charge.json
```

The dry run validates required inputs and prints the request preview to stderr without sending it. Review the method, URL, account header, and body. This preview verifies request construction; the API validates permissions and payment conditions when you send the request.

<Warning>
  `--agent` includes `--yes`, so commands that require confirmation can proceed without another prompt. Obtain approval for the exact write before removing `--dry-run`.
</Warning>

## Read fresh results and handle errors

For a fresh API result, bypass both local fallback and the HTTP response cache:

```bash theme={null}
straddle payments --page-size 10 --data-source live --no-cache --agent
```

List commands return one page by default. Add `--all` when the task requires every page. On reads that include provenance, inspect `meta.source` and `meta.synced_at` to distinguish API results from local data.

Capture stdout, stderr, and the process exit code separately. A failed command can report diagnostics as text on stderr even with `--agent`. Follow the [error recovery guide](/developer-tools/cli/troubleshooting#respond-to-an-error) before retrying a write.

<Accordion title="Call an API path directly">
  Use `straddle api` to discover the raw interfaces. If you have a verified endpoint path, preview it with the shared credentials and account rules:

  ```bash theme={null}
  straddle api get /v1/customers --param page_size=1 --dry-run --agent
  ```

  After reviewing the preview, remove `--dry-run` to send the read. Add `--no-cache` when it must reach the API.
</Accordion>


## Related topics

- [Troubleshoot Straddle skills](/developer-tools/skills/troubleshooting.md)
- [Work with Straddle from your terminal](/developer-tools/cli/overview.md)
- [Choose your tools](/developer-tools/routing.md)
- [Troubleshoot the Straddle CLI](/developer-tools/cli/troubleshooting.md)
- [Use Straddle skills](/developer-tools/skills/use-kit.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.