CLI Reference

The rosql CLI requires the server feature flag.

Install:

curl | sh

curl -fsSL https://rosql.org/install.sh | sh

Linux x86_64 / arm64 · macOS Intel & Apple Silicon.

Homebrew (macOS)

brew install robotopsinc/tap/rosql

cargo install

cargo install rosql --features server,duckdb

All platforms including Windows.

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"

Flags:

• --file <path> — read query from a file instead of a positional argument

---

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, parquet (required; env: ROSQL_BACKEND)
• --schema — column naming profile: otel-postgres (default), otel-clickhouse (env: ROSQL_SCHEMA)
• --file <path> — read query from a file

---

rosql query

Execute a ROSQL query and return results.

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

Output defaults to a human-readable table. Use --format json for scripts.

Flags:

• --backend — driver: postgres, mysql, parquet (env: ROSQL_BACKEND)
• --url — database connection string (env: ROSQL_URL)
• --schema — column naming profile (env: ROSQL_SCHEMA)
• --format — output format: table (default), json, csv
• --no-color — disable ANSI color codes
• --file <path> — read query from a file

If --backend or --url are omitted, they are read from ROSQL_BACKEND / ROSQL_URL environment variables or ~/.config/rosql/config.toml.

---

rosql schema

Inspect which canonical data sources are available on the connected backend.

rosql schema --backend parquet --url ./telemetry/

╭─────────────┬──────────────────┬───────────────╮
│ Source      │ Table            │ Status        │
├─────────────┼──────────────────┼───────────────┤
│ traces      │ otel_traces      │ available     │
│ logs        │ otel_logs        │ available     │
│ metrics     │ otel_metrics     │ not found     │
│ topics      │ topic_messages   │ available     │
│ recordings  │ mcap_metadata    │ not found     │
╰─────────────┴──────────────────┴───────────────╯

Flags:

• --backend — driver (env: ROSQL_BACKEND)
• --url — connection string (env: ROSQL_URL)
• --format — table (default), json, csv
• --no-color — disable color

---

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

Flags:

• --file <path> — read query from a file

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
• Validate — validate syntax
• GetCompletions — get autocomplete suggestions

---

Global flags

Flag	Description
--no-color	Disable ANSI color codes for all output. Auto-disabled when stdout is not a TTY.
--help	Print help for any subcommand.
--version	Print the installed version.

---

Config file

~/.config/rosql/config.toml sets default values for --backend, --url, and --schema.

[default]
backend = "postgres"
url = "postgresql://user:pass@localhost:5432/telemetry"
schema = "otel-postgres"

Precedence: CLI flag > ROSQL_* environment variable > config file > built-in default.

---

Environment variables

Variable	Equivalent flag	Description
ROSQL_BACKEND	--backend	Default backend for query, schema, compile
ROSQL_URL	--url	Default connection URL for query and schema
ROSQL_SCHEMA	--schema	Default schema profile

---

Schema profiles

Profile	Columns	Exporter
otel-postgres (default)	snake_case: trace_id, span_name	OTel Collector PostgreSQL exporter
otel-clickhouse	PascalCase: TraceId, SpanName	OTel Collector ClickHouse exporter

---

Pre-built binaries

Platform	Architecture	Download
Linux	x86_64	GitHub Releases
Linux	aarch64	GitHub Releases
macOS	Apple Silicon (aarch64)	GitHub Releases
macOS	Intel (x86_64)	GitHub Releases

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