zsql CLI
zsql is the command line for 0sql, and the server too. It reads your warehouse to draft a model, validates the model, plans SQL from it, runs a query against the warehouse to check the answer, and serves the model to your application.
Two rules say where a command does its work:
- Anything that needs only the model runs here, from the project directory at hand; anything about a server’s copy of the model takes
-r. - Anything that opens a warehouse connection runs here only.
datasource,catalog,generate,sampleandrunhave no-rform, because the server has no database driver in it. See Connecting to a warehouse.
Install
curl -fsSL https://0sql.io/install.sh | sh
zsql --version
A single static binary, no runtime. Details and the build-from-source route are in Installing zsql.
The loop
A new project, start to finish — the same flow zsql --help prints:
zsql init my-model && cd my-model # project.yml, datasources.yml, security.yml, AGENTS.md, models/, tests/
zsql datasource add # point it at a warehouse (or edit datasources.yml)
zsql catalog read --schema public # read what the warehouse holds into catalog/
zsql generate # pick tables, get a draft model
zsql check # make sure it loads, and matches the catalog
zsql sample # collect values so a question can name one
zsql run 'revenue by region' # ask it something, and see the rows
Then the model goes to a server:
zsql sql 'item category, store net paid' --context user.json
zsql repl --context user.json # the model here, reloaded as the files change
zsql serve # the server, serving this project at 127.0.0.1:3699
zsql -r sql 'item category, store net paid' # the same, against the server's copy
A server elsewhere gets the project with zsql auth (its deploy token, when it has one) and zsql deploy. Each step has a page below.
Inside a project, zsql alone opens the repl; outside one it prints help.
Commands
| Group | Command | Does |
|---|---|---|
| project | zsql init [DIR] | Start a project: templates, AGENTS.md, .gitignore, git init -b main |
| warehouse | zsql datasource list|add|auth|test | The warehouses in datasources.yml, their secrets, and a connection probe |
zsql catalog read|sync|search|show | What the warehouse holds, in catalog/{datasource}.json | |
zsql generate [TABLES...] | Draft model files from the catalog; never rewrites one | |
zsql sample [NAMES...] | Collect the values of the dimensions marked enable_sampling | |
zsql run LINE | Run a planned query and keep its rows under ~/.zsql/results | |
zsql results list|show|export|sql|rm|purge | What zsql run kept | |
| here | zsql check | Load the model, check it against the catalog, run its tests; -r on the server |
zsql test | Run tests/*.yml here; --new NAME writes one; -r runs the deployed branch’s | |
| querying | zsql sql | Plan one query and print the SQL |
zsql explain | SQL plus the node graph and timings | |
zsql explore | What a query can add: dimensions to drill into, measures to join | |
zsql spec LINE | The spec JSON an expression line makes | |
zsql repl | Plan interactively; the model reloads as its files change | |
zsql fields [Q] | Fields of the model | |
zsql tables | Tables of the model | |
zsql values DIM | A dimension’s sampled values | |
| server | zsql serve | Run the server here; inside a project, serve that project |
zsql server start|stop|status|logs|health | The same, kept running in the background | |
zsql auth --api-key TOKEN | Save the server’s deploy token (and optionally the server) in .zsql | |
zsql deploy | Deploy the checked-out branch: model files, tests and sampled values | |
zsql status | The deployed branch’s summary | |
zsql deployments | Every deployment on the server | |
zsql undeploy --yes | Remove the deployed branch | |
| shell | zsql completions SHELL | Completion for bash, zsh or fish |
The querying commands, check, test and values run here by default and on the server with -r. datasource, catalog, generate, sample, run and results are local only. deploy, status, deployments, undeploy and auth are always about a server. (list, remove and health still work as the older names for deployments, undeploy and server health.) Every flag is in the command reference.
Global flags
| Flag | Default |
|---|---|
--project DIR | The directory holding project.yml, here or in a parent |
-r, --remote | Off: use the files here. On: use the server’s copy of the model |
--branch NAME | The checked-out git branch of the project; main outside a project. Only with -r: the files here are what they are |
--server URL | ZSQL_SERVER, else server: in .zsql or ~/.zsql/config, else server: in project.yml, else http://127.0.0.1:3699. Implies -r |
--uid UID | uid from project.yml. Implies -r |
--no-input | Off on a terminal. On, a missing answer is a refusal naming the flag that supplies it. Implied when stdin is not a terminal or CI is set |
--agent | Off. On, every command that answers with data answers in JSON, and nothing ever prompts |
Driving zsql from a program
--agent is the flag for an agent or a script: JSON wherever a command has a JSON shape — queries, results, catalog read, sync, search, show, check, test, sample, datasource list, server status and bare status — and never a prompt. One document per invocation, including when a command answers and then fails: the failure is inside the document and the exit code is unchanged, so a caller parses one thing rather than branching on whether it got JSON or a message.
--json does the same for one command at a time. Either way, every prompt has a flag form that its own refusal names, so a script never waits on a question.
zsql init writes an AGENTS.md into the project: the layout, the flow in its non-interactive form, how to author a field, and the sampling guidance. It is there so an agent editing the model reads the same rules a person would.
Reads need no credential. A deploy, a remote test run and an undeploy send the server’s deploy token when it has one; it comes from ZSQL_API_KEY, else api_key: in .zsql (written by zsql auth), else ~/.zsql/config. Outside a project directory, --uid is required and the branch defaults to main; that is how you query a deployment from a machine that has no checkout. The default server is the one zsql serve binds, so a laptop needs no configuration at all. See Server and deploy token.
A refusal prints as <class>: <message>, for example NotFound: no deployment for project tpcds branch main, whether it was planned here or on the server, and the process exits non-zero.
Pages
- Projects:
zsql init,project.yml, the directory layout, branches - Datasources:
datasources.yml, adapters, tiers - Connecting to a warehouse: the connection keys, secrets, TLS,
zsql datasource - The catalog:
zsql catalog read,sync,search,show - Generating model files:
zsql generate, drafts and inferred joins - Modeling with zsql: the model files and
zsql check - Sampling dimension values:
enable_sampling,zsql sample,zsql values - Server and deploy token:
zsql auth,.zsql, environment variables, server resolution - Deploying:
zsql deploy,--watch,status,deployments,undeploy, branch semantics - Tests:
tests/*.ymlandzsql test - Querying from the CLI:
sql,explain,explore,spec,fields,tables, the repl - Running a query:
zsql runandzsql results - CI/CD: GitHub Actions and GitLab CI
- Command reference: every command, flag, env var and file
The server itself, zsql serve and zsql server, is on Running the server.