Command reference

zsql [GLOBAL FLAGS] <COMMAND> [ARGS]. With no command inside a project directory, zsql starts the repl; outside one it prints help. zsql --version prints the version; zsql <command> --help prints that command’s flags.

Global flags

Flag	Default	Notes
`--project DIR`	the directory holding `project.yml`, searched from the current directory upwards	Error without one: no project.yml here or above; run `zsql init` to start a project
`--branch NAME`	the checked-out git branch of the project; `main` outside a project	The service branch every command targets
`--server URL`	see server resolution	Trailing `/` trimmed
`--uid UID`	`uid` from `project.yml`	Required outside a project directory

Project commands

`zsql init [DIR] [--name NAME] [--uid UID]`

Argument	Default	Notes
`DIR`	`.`	Created if missing. Refused if it holds a `project.yml`.
`--name`	the directory name	`name:` in `project.yml`
`--uid`	slug of the name	Lower-cased

Writes project.yml, datasources.yml, security.yml, models/.keep, tests/.keep; appends to .gitignore; runs git init -q -b main if there is no .git. Existing files are kept.

`zsql new table NAME --datasource DS [--physical-name P] [--domain D]`

Argument	Default	Notes
`NAME`	required	`name:` of the table, Title Case
`--datasource`	required	A key in `datasources.yml`
`--physical-name`	the file stem	Warehouse table name
`--domain`	`core`	Folder under `models/`

Writes models/<domain>/tbl.<stem>.yml; the stem is the slug of NAME with - as _. Refused if the file exists.

`zsql new relation --datasource DS [--domain D]`

Argument	Default
`--datasource`	required
`--domain`	`core`

Writes models/<domain>/rel.<domain>.yml.

`zsql new test NAME`

Writes tests/<stem>.yml.

Service commands

`zsql auth --api-key KEY [--server URL]`

Writes api_key: and optionally server: into .zsql in the project directory (mode 0600). Prints saved to <path>.

`zsql check`

Same as zsql deploy --dry-run.

`zsql deploy [--dry-run] [--watch]`

Flag	Does
`--dry-run`	POST to the validate route instead; the service keeps nothing
`--watch`	Deploy, then redeploy whenever a `.yml` or `.yaml` under the project changes (poll 500 ms, debounce 200 ms)

Exits non-zero on a rejected archive or any failed test.

`zsql test`

Runs the deployed branch’s tests on the service. Exits non-zero with tests failed.

`zsql status`

Prints the deployed branch’s summary as JSON.

`zsql list`

One line per deployment: project branch N tables, N fields, N policies, N tests. Works outside a project.

`zsql remove --yes`

Removes the deployed branch. Without --yes: this removes <uid>/<branch> from <server>; add --yes to confirm.

`zsql health`

Prints <server> ok. No key needed.

Query commands

The three planning commands share the query arguments:

Flag	Notes
`--spec FILE`	A JSON file; a top-level `spec` key is unwrapped. Conflicts with `--expr`.
`--expr LINE`	A shorthand line, parsed locally into a spec
`--context FILE`	A JSON security context

One of --spec or --expr is required.

`zsql sql (--spec FILE | --expr LINE) [--context FILE] [--explain] [--json]`

Flag	Does
`--explain`	Same output as `zsql explain`
`--json`	Print the service’s response as JSON

Prints corrections (stderr), -- datasource: <name>, the SQL.

`zsql explain (--spec FILE | --expr LINE) [--context FILE] [--json]`

Corrections, -- datasource:, SQL, blank line, -- N nodes, the node tree, -- server N us: parser N us, plan N us, -- phases (us): ....

`zsql explore (--spec FILE | --expr LINE) [--context FILE] [-q TERM] [--json]`

Flag	Does
`-q TERM`	Keep fields whose name, uid or synonyms contain the term, or come close

Lines of uid dim|msr name tables [~score], then -- can add N dimensions, N measures · server N us.

`zsql spec LINE...`

Prints the spec JSON a shorthand line makes. Local; no server, no key.

`zsql repl [--context FILE]`

Flag	Does
`--context FILE`	Security context applied to every query in the session

Dot-commands: .help .? .tables .fields [q] .branch [name] .spec <line> .json {...} .explain <line|json> .explore <line|json> [? term] .quit .exit .q. History in ~/.zsql/history.

`zsql fields [Q] [--hidden]`

Argument	Does
`Q`	Filter text; containing matches first, then fuzzy with a score
`--hidden`	Include hidden fields

Lines of uid dim|msr name [(hidden)] [~score].

`zsql tables`

Lines of uid physical_name datasource cost N.

Environment variables

Variable	Used for
`ZSQL_API_KEY`	The API key. Wins over every file.
`ZSQL_SERVER`	The server URL. Second after `--server`.
`HOME`	Locates `~/.zsql/config` and `~/.zsql/history`

Server resolution: --server, ZSQL_SERVER, server: in .zsql (or .strata), server: in ~/.zsql/config, server: in project.yml, then http://127.0.0.1:3699.

Key resolution: ZSQL_API_KEY, api_key: in .zsql (or .strata), api_key: in ~/.zsql/config.

Config files

File	Holds	Notes
`project.yml`	`name`, `uid`, `production_branch`, optional `server`	Committed. Found by walking up from the current directory.
`.zsql`	`api_key`, `server`	Project directory. Written by `zsql auth`, mode 0600, gitignored. YAML.
`.strata`	Same keys	Read only when `.zsql` is absent.
`~/.zsql/config`	`api_key`, `server`	Account-wide fallback. YAML.
`~/.zsql/history`	repl history
`datasources.yml`	Warehouses	Shipped with secret keys removed

Exit codes and errors

zsql exits 0 on success and non-zero on any error. Errors print as Error: <message>. A service error prints its class and message, <class>: <message>:

Unauthorized: an API key is required: Authorization: Bearer <key>
Forbidden: query keys are read only; deploy with your personal key
NotFound: no deployment for project tpcds branch main
ContextRequired: this branch has security policies; a context is required to plan
DeployError: Error in models/store/tbl.store_sales.yml:
	Expression errors for Store Net Paid: Sql measure should have an aggregation function

zsql deploy and zsql test exit non-zero after a successful HTTP call when any test failed (tests failed). The complete error class table is on Query errors and in the API reference.