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

# Agent & Automation

> Use the MyTruv CLI from scripts and AI agents.

The MyTruv CLI is designed to be called by scripts and AI agents, not just humans. Every command returns structured JSON on stdout, keeps human output on stderr, and signals failures with meaningful exit codes.

***

## Output contract

* **stdout** carries data. JSON by default when piped, or CSV with `--output csv`.
* **stderr** carries human-friendly output (colors, tables, warnings) and structured error JSON on failure - ignored by data parsers.
* When run in a TTY, commands render a formatted table on stderr and stdout stays empty. When piped or redirected, stdout is raw JSON.
* Force a specific format with `--json` (shorthand for `--output json`) or `-o csv`.

```bash theme={null}
mytruv balances                  # TTY: table on stderr, stdout empty
mytruv balances --json           # JSON on stdout, even in a TTY
mytruv balances --output csv     # CSV on stdout
mytruv balances | cat            # piped: JSON on stdout (auto-detected)
mytruv balances > balances.json  # persist JSON to a file
```

***

## Exit codes

| Code | Meaning                                |
| ---- | -------------------------------------- |
| `0`  | Success                                |
| `1`  | Error (API error, network error, etc.) |
| `2`  | Authentication required                |

***

## Error format

Errors are structured JSON on **stderr** (never on stdout, so they never pollute parseable output):

```json theme={null}
{"error": "auth_required", "message": "Not authenticated. Run 'mytruv auth login' first."}
```

***

## Examples

```bash theme={null}
# Sum your checking balances
mytruv balances | jq '[.aggregated_balances[] | select(.type=="CHECKING") | (.balance | tonumber)] | add'

# Top 5 merchants over the last 30 days (only the field matching --group-by is populated)
mytruv spending --days 30 --group-by merchant \
  | jq '.spending.by_merchant[0:5] | map({merchant_name, total_amount, transaction_count})'

# Pull transactions in a date range and count by category
mytruv transactions --from 2026-01-01 --to 2026-04-01 \
  | jq '[.transactions[] | .categories[]] | group_by(.) | map({cat: .[0], n: length})'

# Net worth time series
mytruv balance-history --date-range 1y --time-period month | jq '.time_series'

# Guard a script on authentication
if ! mytruv auth status | jq -e '.authenticated' > /dev/null 2>&1; then
    echo "Please run: mytruv auth login" >&2
    exit 1
fi
```

***

## Gemini CLI extension

MyTruv CLI ships as a [Gemini CLI](https://github.com/google-gemini/gemini-cli) extension, giving Gemini direct access to your financial data through MCP.

Install and authenticate the `mytruv` CLI first (see [Overview](/mytruv-cli/overview#install)) so it is on your `$PATH`, then:

```bash theme={null}
gemini extensions install https://github.com/truvhq/mytruv-cli
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Overview" icon="terminal" href="/mytruv-cli/overview">
    Install, commands, and quickstart
  </Card>

  <Card title="MyTruv MCP" icon="plug" href="/mytruv-mcp/overview">
    Hosted MCP server (no install)
  </Card>
</CardGroup>