# Query

`query run` runs an [ActualQL](https://actualbudget.org/docs/api/actual-ql/) query against your budget. Use it when a `list` command isn't enough: across all accounts, with joins to payee and category names, or with your own filters.

```bash
fob-actual query run --table transactions \
  --select date,amount,payee.name,category.name \
  --filter '{"amount":{"$lt":0}}' --order-by date --desc --limit 10
```

```text
date        amount   payee.name        category.name      id
----------------------------------------------------------------------------------------------
2026-10-03  -45000   Starting Balance  Starting Balances  090a9ac8-905a-4e52-9c11-305bfb1509f4
2026-09-10  -6299    Corner Grocery    Groceries          dd602fe0-20fa-497f-ba01-91372db9565e
2026-09-05  -8423    Corner Grocery    Groceries          79bf3280-f439-44b2-aed4-3fb5ddc0306c
2026-09-01  -180000  Landlord          Rent               02601a62-438b-4cc8-856e-7a56d42a2923
```

Amounts are Actual's integer minor units here (`-6299` is −62.99), and every row includes its `id`.

## Options

| Option | |
| --- | --- |
| `--table` | `transactions`, `accounts`, `categories`, `payees`, `schedules` and other ActualQL tables |
| `--select a,b.c` | Columns, including joined fields such as `payee.name` and `category.name` |
| `--filter '<json>'` | An ActualQL filter. Repeat it to add conditions; all must match |
| `--order-by <field>` and `--desc` | Sort |
| `--limit <n>` | Maximum rows |
| `--query '<json>'` or `--file <path>` | A whole serialized query instead of the options above |
| `--format csv` | CSV instead of a table |
| `--json` | The raw result, `{ "data": [...], "dependencies": [...] }` |

Filters use ActualQL operators such as `$eq`, `$lt`, `$gte`, `$oneof` and `$like`:

```bash
# Grocery spending this year
fob-actual query run --table transactions --select date,amount,payee.name \
  --filter '{"category.name":"Groceries"}' --filter '{"date":{"$gte":"2026-01-01"}}'

# Uncategorized transactions in any account
fob-actual query run --table transactions --select date,account.name,payee.name,amount \
  --filter '{"category":null}'
```

See the [ActualQL documentation](https://actualbudget.org/docs/api/actual-ql/) for every operator, function and table.