CLI for Agents

The tl CLI is designed for programmatic use. Every command supports --json for structured output, making it easy for agents to parse results and chain operations.

Structured Output

Add --json to any command for machine-readable output:

tl status --json

{
  "total_accounts": 3,
  "total_transactions": 847,
  "total_snapshots": 920,
  "total_integrations": 1,
  "integration_names": ["simplefin"],
  "accounts": [
    { "id": "a1b2c3d4-...", "name": "Checking (1234)", "institution_name": "First National Bank" },
    { "id": "e5f6a7b8-...", "name": "Rewards Card (5678)", "institution_name": "Example Credit Union" }
  ],
  "date_range": { "earliest": "2025-06-20", "latest": "2026-03-10" }
}

Query results use a columns + rows format:

tl query "SELECT posted_date, amount, description FROM transactions LIMIT 2" --json

{
  "columns": ["posted_date", "amount", "description"],
  "rows": [
    ["2025-10-02", -45.30, "WHOLE FOODS MARKET #10234"],
    ["2025-10-05", -12.75, "CORNER COFFEE SHOP"]
  ],
  "row_count": 2
}

Key Commands for Agents

Read Operations (Safe)

Command	Description
tl status --json	Account balances, transaction counts, integrations
tl schema --json	Database schema (tables, views, columns, types)
tl query "SQL" --json	Read-only SQL query (database opened read-only)
tl skills list --json	List user-created skills
tl skills read <path>	Read a skill file
tl doctor --json	Database health checks

Write Operations

Command	Description
tl query "SQL" --allow-writes	SQL with write access (INSERT, UPDATE, DELETE)
tl sync --json	Sync from connected bank integrations
tl tag <tag> --ids "id1,id2"	Apply tags to transactions
tl import file.csv --account "Name"	Import transactions from CSV

Schema Introspection

# List all tables and views with their columns
tl schema --json

# Describe a specific table or view
tl schema transactions --json

The tl schema command is purpose-built for agents — it returns structured JSON with table names, types, column names, data types, and nullability. See the Database Schema reference for documentation.

Safe vs. Write Queries

By default, tl query opens the database in read-only mode. This means agents can freely explore data without risk of accidental modification:

# Safe — database opened read-only
tl query "SELECT SUM(-amount) FROM transactions WHERE tags @> ['groceries']" --json

# Requires explicit opt-in
tl query "UPDATE sys_transactions SET tags = ['food'] WHERE description ILIKE '%grocery%'" --allow-writes

The MCP server enforces this same separation with distinct query (read-only) and query_write (write-enabled) tools.

Output Formats

tl query "SELECT * FROM transactions LIMIT 5"               # Table (human-readable)
tl query "SELECT * FROM transactions LIMIT 5" --json         # JSON (for agents)
tl query "SELECT * FROM transactions LIMIT 5" --format csv   # CSV (for export)

Error Handling

Query errors are returned as plain text on stderr:

tl query "SELECT * FROM nonexistent_table" --json

Catalog Error: Table with name nonexistent_table does not exist!

Agents should check the exit code (non-zero on failure) and parse stderr for error details.