The qod CLI
qod is a single command-line client for both planes of quack-on-demand: the manager's admin REST surface on :20900 (tenants, databases, pools, nodes, RBAC, catalog, federation, audit, usage) and the FlightSQL query plane on :31338 (qod sql, one-shot or interactive). Every REST path has a matching noun-verb command - POST /api/tenant/create is qod tenant create, GET /api/pool/list is qod pool list, and so on - so if you know the API you already know most of the CLI.
It is also the launcher: qod serve --demo runs the self-contained demo, qod serve <target> boots a persistent gateway over your own data (a .duckdb file, a parquet/csv directory, or an object-store prefix) on an embedded Postgres, and qod start / qod stop run a real manager against your own Postgres - see Installation and the manager jar reference. And it bundles the operator skill for AI agents: qod skill install teaches Claude Code, Copilot, or Gemini to drive all of the above.
Install
pip install qod
The CLI is released on PyPI as qod (with qod-cli kept as a compatibility alias) on the same version number as the manager itself, so pin the CLI to the manager you are talking to. Requires Python 3.10 or later.
To install from a source checkout instead (for example while developing the CLI itself):
pip install ./cli
Both routes install the qod console script on $PATH.
Windows. The same pip install qod installs a qod.exe entry point; there is no separate Windows package. The profile file lives at ~/.qod/config.toml as on every platform, and the interactive qod sql REPL gets line editing and history from pyreadline3 (installed automatically as a Windows-only dependency).
Login and profiles
qod login --url http://localhost:20900 --username admin
Against the demo bootstrap this prompts for the admin / admin dev password (the password is always a prompt, never a flag, so it never lands in shell history). A successful login mints a session and writes it to the active profile together with the FlightSQL edge settings the manager reports back (host, port, TLS) - one qod login configures both the REST plane and the SQL plane in one shot.
Profiles are named sections of a TOML file at ~/.qod/config.toml on every platform (override the whole path with QOD_CONFIG_FILE; a file left at the former platform config directory is moved there on first use). The file is written with mode 0600 because it can hold a session token and, opt-in, a SQL password. The default profile is named default; switch profiles with --profile prod (a top-level flag, before the noun) or the QOD_PROFILE environment variable, so one machine can hold a default profile against a local dev manager and a prod profile against a real deployment without either clobbering the other. qod config profiles lists the profiles the file holds and marks the active one; qod config use <name> makes a profile the sticky default so you can drop the flag.
The CLI has one REST credential, token, sent as X-API-Key: the session qod login writes, or a personal access token. For non-interactive callers such as CI, either set QOD_TOKEN to a personal access token an admin minted once (qod auth pat create), or run qod login --password-stdin inside the job (the password on the first line of stdin, never in a flag or an env var). There is no static API key: a 401 from the CLI says "run qod login, or set QOD_TOKEN to a personal access token".
Settings resolution
Every setting resolves in this order, highest priority first:
- Command-line flag (
--tenant,--url, ...) QOD_*environment variable- Value saved in the active profile
- Built-in default
| Setting | Env var | Notes |
|---|---|---|
manager_url | QOD_MANAGER_URL | REST plane base URL. |
token | QOD_TOKEN | The only REST credential: the session JWT qod login writes, or a personal access token set by hand. |
edge_host | QOD_HOST | FlightSQL edge host. |
edge_port | QOD_PORT | FlightSQL edge port. |
edge_tls | QOD_TLS | TLS to the edge. |
edge_tls_verify | QOD_TLS_VERIFY | Verify the edge TLS cert; off by default since the edge ships a self-signed cert. |
tenant | QOD_TENANT | Default tenant for qod sql. |
pool | QOD_POOL | Default pool for qod sql. |
branch | QOD_BRANCH | Branch qod sql targets (sent as the FlightSQL branch header). |
sql_user | QOD_USER | FlightSQL username; set by qod login. |
sql_password | QOD_PASSWORD | FlightSQL password; opt-in storage, prompted when unset. |
superuser | QOD_SUPERUSER | Send the superuser call header on qod sql. |
Output
Rich tables are the default, sized to the terminal. Pass --json - a top-level flag, before the noun - for the raw JSON response body, the stable interface for scripting:
qod --json tenant list | jq -r '.[].id'
qod sql additionally supports --csv for spreadsheet-friendly output, and
--file <path> (or -f; - reads stdin) to run a SQL script: statements
are split on top-level semicolons with full lexical awareness (strings,
quoted identifiers, comments, dollar-quoting), executed in order, and the
first error aborts with exit 1 naming the failing statement and its line -
unlike piping into the interactive REPL, which prints prompts and keeps
going after errors. Exit codes follow the Unix convention: 0 success, 1 a server or API error (the server's error body is printed verbatim, e.g. tenant_forbidden), 2 a usage error (missing or invalid arguments).
Where to go next
- Administering with the CLI - a full walkthrough provisioning a tenant, database, pool, users, and RBAC.
- Running SQL - one-shot queries, the REPL, and time travel.
- Command reference - every noun and verb.