> ## 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 and output results in table, JSON, or CSV format.

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" | 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.
* Pipe the output to `jq` for JSON processing in scripts.