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

# Query

> Run ClickHouse SQL queries against your Formo analytics data warehouse directly from the terminal, with results in TOON, JSON, or other output formats.

The `formo query run` command lets you execute SQL queries against your Formo analytics data warehouse directly from the terminal.

## `formo query run <sql>`

Run a SQL query against your Formo analytics data.

<Note>
  Requires `query:read` scope on your API key.
</Note>

### Arguments

| Argument | Type | Required | Description |
| - | - | - | - |
| `sql` | `string` | ✅ | SQL query string to execute |

### Examples

```bash theme={null}
# Count all events
formo query run "SELECT count(*) FROM events"

# Top 10 wallets by net worth
formo query run "SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net_worth_usd DESC LIMIT 10"

# Daily active users over the last 7 days
formo query run "SELECT DATE(timestamp) as day, COUNT(DISTINCT address) as dau FROM events WHERE timestamp > now() - INTERVAL 7 DAY GROUP BY day ORDER BY day"

# Pipe results to jq for processing
formo query run "SELECT count(*) as total FROM events" --json | jq '.data'
```

### Tips

* SQL queries execute against your project's analytics data warehouse.
* Wrap your query in double quotes to prevent shell interpretation.
* Use single quotes inside your SQL for string literals.
* Pass `--json` and pipe the output to `jq` for processing in scripts (default output is TOON).


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