---
title: "coding.sh sql · coding.sh docs"
description: "Run one read-only SQL query against the SQLite index. Every option of coding.sh sql, from its own --help."
canonical: https://coding.sh/docs/cli/sql
human_url: https://coding.sh/docs/cli/sql
markdown_url: https://coding.sh/docs/cli/sql.md
agents_url: https://coding.sh/agents.md
llms_url: https://coding.sh/llms.txt
updated: 2026-11-11
---

# coding.sh sql

Run one read-only SQL query against the SQLite index. Every option of coding.sh sql, from its own --help.

coding.sh sql --help

```
coding.sh sql <QUERY>... [options]

  Run one read-only SQL query against the SQLite index

Arguments
  query         One SELECT or WITH statement

Options
      --csv                Print CSV instead of a table
  -n, --limit <N>          Most rows to return (default: 1000)
      --timeout <SECONDS>  Stop the query after this long (default: 10)
      --fresh              Wait for every pending capture to be ingested (default: answer after 1.5 s)

Examples
  coding.sh sql "select agent, count(*) as n from sessions group by agent"
  coding.sh sql "select tool, count(*) from events where kind = 'tool.end' and ok = 0 group by tool order by 2 desc" --csv
  coding.sh sql "select name, sql from sqlite_schema where type = 'table'"

Notes
  Read-only: the index is opened read-only with query_only on, and only one SELECT or WITH statement is accepted. INSERT, UPDATE, DELETE, ATTACH, PRAGMA statements and a second statement exit 2.
  Postgres and ClickHouse stores are not supported here: use coding.sh export, or the database's own client.
  Tables and columns: docs/reference/query.md. Events keep their payload as JSON text: json_extract(payload, '$.command').
```

[All commands](https://coding.sh/docs/cli) · [Global options](https://coding.sh/docs/cli#global)

To set coding.sh up for a user, follow the agent workflow at [/agents.md](https://coding.sh/agents.md).