CLI Reference

The rosql CLI requires the server feature flag:

cargo install rosql --features server,postgres

Commands

rosql parse

Parse a ROSQL query and output the AST as JSON.

rosql parse "FROM traces WHERE duration > 500 ms SINCE 1 hour ago"

Useful for inspecting the parsed structure of a query and verifying syntax.

---

rosql compile

Compile a ROSQL query to SQL. No database connection required.

rosql compile "FROM traces WHERE duration > 500 ms" --backend postgres

SELECT * FROM otel_traces
WHERE duration > 500000000
ORDER BY timestamp DESC
LIMIT 100

Flags:

• --backend — target SQL dialect: postgres, mysql (required)
• --schema — column naming profile: otel-postgres (default), otel-clickhouse

---

rosql query

Execute a ROSQL query and return results as JSON.

rosql query "FROM traces WHERE status = 'ERROR'" \
  --backend postgres \
  --url postgresql://user:pass@localhost:5432/db

Flags:

• --backend — driver: postgres, mysql (required)
• --url — database connection string (required)
• --schema — column naming profile

---

rosql validate

Validate ROSQL query syntax. Exits with code 0 if valid, 1 if invalid.

rosql validate "SELECT * FROM logs"
# exit 0 — valid

rosql validate "INSERT INTO logs"
# exit 1 — invalid: INSERT not supported

Useful in CI pipelines to validate stored queries.

---

rosql completions

Get autocomplete suggestions at a given cursor position.

rosql completions "FROM " 5

[
  {"label": "logs", "kind": "DataSource"},
  {"label": "traces", "kind": "DataSource"},
  {"label": "metrics", "kind": "DataSource"},
  {"label": "topics", "kind": "DataSource"}
]

Arguments:

• <query> — partial query string
• <cursor> — cursor position (byte offset)

---

rosql serve

Start the gRPC server on a Unix socket. Used by language server integrations and IDE plugins.

# Default socket path
rosql serve --socket /tmp/rosql.sock

# Custom socket path
rosql serve --socket /run/rosql/rosql.sock

The server exposes the ParserService proto interface (defined in proto/rosql/v1/). It accepts:

• Parse — parse a query
• Compile — compile to SQL
• Validate — validate syntax
• GetCompletions — get autocomplete suggestions

---

Schema profiles

All commands that interact with a database accept --schema:

# lowercase columns (PostgreSQL default OTel exporter)
rosql query "FROM traces" --backend postgres --schema otel-postgres

# PascalCase columns (ClickHouse OTel exporter)
rosql query "FROM traces" --backend clickhouse --schema otel-clickhouse

Pre-built binaries

Platform	Architecture	Download
Linux	x86_64	GitHub Releases
Linux	aarch64	GitHub Releases

Other platforms: build from source (see Quickstart →).