Skip to main content
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.
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

CodeMeaning
0Success
1Error (API error, network error, etc.)
2Authentication required

​
Error format

Errors are structured JSON on stderr (never on stdout, so they never pollute parseable output): 
{"error": "auth_required", "message": "Not authenticated. Run 'mytruv auth login' first."}

​
Examples

# 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 extension, giving Gemini direct access to your financial data through MCP. Install and authenticate the mytruv CLI first (see Overview) so it is on your $PATH, then: 
gemini extensions install https://github.com/truvhq/mytruv-cli

​
Next steps

CLI Overview

Install, commands, and quickstart

MyTruv MCP

Hosted MCP server (no install)