CLI - Spiral Docs

The spiral binary is the top-level command surface. spiral-cli links built-in subcommands directly from focused CLI crates:

Command	Implementation crate	Purpose
`spiral sql`	`spiral-cli-sql`	Run SQL once or start an interactive SQL REPL over the active Spiral session.
`spiral flight`	`spiral-cli-flight`	Start an Arrow Flight SQL server for query results.
`spiral serve`	`spiral-cli-serve`	Start a localhost HTTP query server for browser previews.
`spiral orgs`, `spiral projects`	`spiral-cli-admin`	Manage organizations, projects, and grants.

Standalone binaries such as spiral-sql, spiral-flight, spiral-serve, and spiral-admin remain available for crate-local development.


spiral sql
spiral sql -c "SELECT 1 AS id;"

From a source checkout, use:


./target/debug/spiral sql

or:


cargo run -p spiral-cli -- sql

Synopsis


spiral <COMMAND>
spiral sql [--threads <N>] [--max-rows <N>] [--max-columns <N>] [--max-cell-width <N>] [--project <PROJECT>] [--dataset <DATASET>] [--trace[=<PATH>]] [--trace-ui] [-c <SQL>]
spiral flight [--bind <ADDR>] [--advertised-location <URI>] [--threads <N>] [--io-threads <N>]
spiral serve [--bind <ADDR>] [--allow-origin <ORIGIN>] [--ui-url <URL>] [--no-open-ui] [--threads <N>] [--io-threads <N>]
spiral app
spiral-sql [--threads <N>] [--max-rows <N>] [--max-columns <N>] [--max-cell-width <N>] [--project <PROJECT>] [--dataset <DATASET>] [--trace[=<PATH>]] [--trace-ui] [-c <SQL>]
spiral-flight [--bind <ADDR>] [--advertised-location <URI>] [--threads <N>] [--io-threads <N>]
spiral-serve [--bind <ADDR>] [--allow-origin <ORIGIN>] [--ui-url <URL>] [--no-open-ui] [--threads <N>] [--io-threads <N>]

SQL flags

Flag	Meaning
`--threads <N>`	Engine worker count. Defaults to twice the available parallelism.
`--max-rows <N>`	Maximum result rows the REPL asks the engine to collect for display. Defaults to `100`; the REPL requests one extra row to report whether more rows are available.
`--max-columns <N>`	Maximum result columns printed. Defaults to fitting the terminal width; use `0` to show all columns.
`--max-cell-width <N>`	Per-header or per-cell cap used only when the result table would exceed the display width. Defaults to `32`; use `0` for unbounded text.
`--project <PROJECT>`	Set the current SpiralDB project for bare table names at startup. Equivalent to running `USE PROJECT <PROJECT>`.
`--dataset <DATASET>`	Set the current SpiralDB dataset for bare table names at startup. Defaults to `default`; equivalent to running `USE DATASET <DATASET>`.
`--trace`	Capture query execution as a Perfetto trace using the default output path.
`--trace=<PATH>`	Capture query execution as a Perfetto trace at the given path.
`--trace-ui`	Capture the one-shot command trace, serve it from `127.0.0.1:9001`, and open the hosted trace in the Perfetto UI. Requires `-c` or `--command`; use `--trace=<PATH>` to choose the trace file.
`-c <SQL>`, `--command <SQL>`	Execute one SQL statement and exit. When omitted, `spiral sql` starts the interactive REPL.

The SQL REPL installs the legacy SpiralDB catalog as the default relation catalog. Local REPL tables remain in the memory catalog, so refer to them as memory.<table> when a query should use local state instead of SpiralDB.

Flight SQL server


spiral flight --bind 127.0.0.1:50051

During crate-local development, run the server crate directly to avoid building the full CLI:


cargo run -p spiral-flight -- --bind 127.0.0.1:50051

The Flight server accepts Flight SQL CommandStatementQuery messages in FlightDescriptor::CMD. GetFlightInfo returns a single ordered endpoint whose ticket is a Flight SQL TicketStatementQuery. DoGet executes that ticket and streams Arrow record batches. GetSchema returns the query schema without execution. CommandGetSqlInfo returns a small static server-info response.

Flag	Meaning
`--bind <ADDR>`	Socket address to listen on. Defaults to `127.0.0.1:50051`.
`--advertised-location <URI>`	Optional URI added to Flight endpoints. When omitted, endpoints are redeemable on the current service.
`--threads <N>`	Engine worker count. Defaults to twice the available parallelism.
`--io-threads <N>`	IO thread count for the engine runtime. Defaults to `2`.

Prepared statements, transactions, Substrait plans, bulk ingestion, DoPut, DoExchange, actions, and PollFlightInfo are explicitly unsupported. Use the spql.vortex.read(path), spql.arrow.read_ipc(path), and spql.parquet.read(path) table functions to query local files.

Local HTTP query server


spiral serve --bind 127.0.0.1:4810

During crate-local development, run the server crate directly:


cargo run -p spiral-serve -- --bind 127.0.0.1:4810

The server is intended for a browser UI running on the same machine. It prints a pairing URL containing the localhost endpoint and a random local token, then opens it in the default browser unless --no-open-ui is passed. The browser sends that token as Authorization: Bearer <token> or x-spiral-local-token: <token> for query execution.

Endpoint	Meaning
`GET /v1/health`	Return service health. Does not require the local token.
`GET /v1/capabilities`	Return supported request and response formats. Does not require the local token.
`POST /v1/query`	Execute one relation-producing SQL statement. Requires the local token.

POST /v1/query accepts application/json:


{
  "sql": "SELECT 1 AS id",
  "max_rows": 100
}

It returns JSON preview rows by default. Send Accept: application/vnd.apache.arrow.stream to receive Arrow IPC stream bytes. The initial server accepts SQL only; protobuf relation plans and Vortex IPC are planned future wire formats.

Flag	Meaning
`--bind <ADDR>`	Socket address to listen on. Defaults to `127.0.0.1:4810`.
`--allow-origin <ORIGIN>`	Exact browser origin allowed by CORS. Can be repeated or comma-delimited. Defaults to local Next.js origins and `https://app.spiraldb.com`.
`--ui-url <URL>`	Web UI URL used in the printed pairing URL. Defaults to `http://localhost:3000/local`.
`--no-open-ui`	Print the pairing URL without opening it in the default browser.
`--threads <N>`	Engine worker count. Defaults to twice the available parallelism.
`--io-threads <N>`	IO thread count for the engine runtime. Defaults to `2`.

Dot commands

Command	Meaning
`.open <table> <path> [path ...] [--key col[,col...]]`	Register one or more Vortex files as a table. `--key=col[,col...]` is also accepted.
`.load <table> <path> [path ...] [--key col[,col...]]`	Alias for `.open`. `--key=col[,col...]` is also accepted.
`.tables`	List registered tables.
`.schema [table]`	Show one table schema, or all table schemas.
`.help`	Print REPL help.
`.quit` / `.exit`	Leave the REPL.

Dot commands are interpreted by the REPL and do not end with ;.

SQL input

Interactive SQL input must end with ;.


SELECT 1;

Multi-line input continues until the terminating semicolon:


SELECT category, count(*)
FROM events
GROUP BY category;

The REPL accepts one SQL statement at a time.

For non-interactive execution, pass the SQL statement with -c or --command:


spiral sql -c "SELECT 1 AS id;"

To inspect a one-shot command trace in Perfetto:


spiral sql --trace-ui --trace=/tmp/query.pftrace -c "SELECT 1 AS id;"

--trace-ui opens https://ui.perfetto.dev with a localhost trace URL and keeps the local trace server running on 127.0.0.1:9001 until the process is interrupted. That fixed port matches Perfetto UI’s browser content-security policy for localhost trace URLs.

Loading files


.open events ./events.vortex


.open events ./part-000.vortex ./part-001.vortex ./part-002.vortex

Declare a sorted unique key:


.open orders ./orders.vortex --key o_orderkey
.open lineitem ./lineitem.vortex --key=l_orderkey,l_linenumber

Only declare a key when the data is sorted by that key and key values are unique.

Output

Query output is printed as an ASCII table. --max-rows limits the number of rows collected for REPL display, and the REPL requests one extra row so it can print more rows available. Add an explicit SQL ORDER BY ... LIMIT when you need a deterministic top-N result rather than a display preview. --max-columns and --max-cell-width control only terminal formatting.

History

The REPL stores history in $SPIRAL_HISTORY when set. Otherwise it tries ~/.spiral_history and falls back to in-memory history if no history file can be opened.

Completion

The REPL includes basic completions for dot commands and common SQL keywords.