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, sample and run have no -r form, 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

GroupCommandDoes
projectzsql init [DIR]Start a project: templates, AGENTS.md, .gitignore, git init -b main
warehousezsql datasource list|add|auth|testThe warehouses in datasources.yml, their secrets, and a connection probe
zsql catalog read|sync|search|showWhat 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 LINERun a planned query and keep its rows under ~/.zsql/results
zsql results list|show|export|sql|rm|purgeWhat zsql run kept
herezsql checkLoad the model, check it against the catalog, run its tests; -r on the server
zsql testRun tests/*.yml here; --new NAME writes one; -r runs the deployed branch’s
queryingzsql sqlPlan one query and print the SQL
zsql explainSQL plus the node graph and timings
zsql exploreWhat a query can add: dimensions to drill into, measures to join
zsql spec LINEThe spec JSON an expression line makes
zsql replPlan interactively; the model reloads as its files change
zsql fields [Q]Fields of the model
zsql tablesTables of the model
zsql values DIMA dimension’s sampled values
serverzsql serveRun the server here; inside a project, serve that project
zsql server start|stop|status|logs|healthThe same, kept running in the background
zsql auth --api-key TOKENSave the server’s deploy token (and optionally the server) in .zsql
zsql deployDeploy the checked-out branch: model files, tests and sampled values
zsql statusThe deployed branch’s summary
zsql deploymentsEvery deployment on the server
zsql undeploy --yesRemove the deployed branch
shellzsql completions SHELLCompletion 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

FlagDefault
--project DIRThe directory holding project.yml, here or in a parent
-r, --remoteOff: use the files here. On: use the server’s copy of the model
--branch NAMEThe checked-out git branch of the project; main outside a project. Only with -r: the files here are what they are
--server URLZSQL_SERVER, else server: in .zsql or ~/.zsql/config, else server: in project.yml, else http://127.0.0.1:3699. Implies -r
--uid UIDuid from project.yml. Implies -r
--no-inputOff 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
--agentOff. 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

The server itself, zsql serve and zsql server, is on Running the server.