Global Flags

Global flags specify runtime program behavior for the StackQL application, these flags are set at the command line when the StackQL application is launched (in either the interactive/shell mode or non-interactive exec mode) or are sourced from the StackQL initialization (.stackqlrc) file. Flags include:

Flag	Data Type	Description	Default
--access.config	string	Caller access configuration, a JSON envelope {"path": "/path/to/access.json"} (a bare file path is also accepted). Enables access management: callers are authenticated by JWT, static bearer token, mutual TLS or local OS identity and statements are authorised against policy rules. Local token credentials are read from STACKQL_CALLER_TOKEN. Available in StackQL releases from v1.0.
--acid	string	JSON / YAML string representing ACID config	{}
--allow-persistent-secrets	flag	Allow a session to select a persistent OS secret store (macOS Keychain, Linux Secret Service or Windows Credential Manager) with SET "$.secret_store". Flat-file stores are refused even with the flag. See Provider Sessions and Secrets. Available in StackQL releases from v1.0.	false
--allow-secret-dereference	flag	Allow secret and credential values to be dereferenced in SQL expressions ("$secrets.name", "$auth.provider.field"), with the consequence that they can enter results, logs and persisted query artefacts. Not needed for normal provider authentication. See Secret values in SQL. Available in StackQL releases from v1.0.	false
--apirequesttimeout	integer	API request timeout in seconds, 0 for no timeout	45
--approot	string	Application config and cache root path	{cwd}/.stackql
--approotfilemode	uint32	Application config and cache file mode	493
--auth	string	auth context keyvals in json form
--cachekeycount	integer	Cache initial key count	100
--configfile	string	Config file full path	{cwd}/.stackqlrc
--cpuprofile	string	cpuprofile file, none if empty	null
--dataflow.dependency.max	int	Maximum dataflow dependency depth for a given query	50
--dataflow.components.max	int	Maximum dataflow weakly connected components for a given query	50
--dbInternal	string	JSON / YAML string to configure DBMS housekeeping query handling	{}
-d, --delimiter	string	Delimiter for csv output. Single char only.  Ignored for all non-csv output	,
--dryrun	flag	dryrun flag; run preprocessor only, templated output will be returned	false
--env.file	string	Optional dotenv-style file sourced into the process environment at startup (all commands); the MCP reload_credentials tool re-sources it on demand. A missing file is tolerated; keys with empty values are skipped; existing variables are overwritten. Not sourced from .stackqlrc. Available in StackQL releases after v0.10.542.	null
--execution.concurrency.limit	int	Concurrency limit for query execution	1
--export.alias	string	Export alias prefix (namespace or schema)
--gc	string	JSON / YAML string representing GC config	{}
-H, --hideheaders	flag	Disables column headers, valid only with --output csv or --output text	false
--http.log.enabled	flag	Display http request info in terminal	false
--http.proxy.host	string	Proxy host (leave blank for no proxy)	null
--http.proxy.password	string	Proxy password	null
--http.proxy.port	integer	Proxy port, any number less than or equal to 0 will result in the default port for a given scheme (e.g. http -> 80)	-1
--http.proxy.scheme	string	Proxy scheme, http or https	http
--http.proxy.user	string	Proxy user	null
--http.response.maxResults	integer	Maximum results per http request, any number less than or equal to 0 results in no limitation	-1
--http.response.pageLimit	integer	Maximum pages of results that will be returned per resource, any number less than or equal to results in no limitation	20
--indirect.depth.max	integer	Maximum depth for indirect queries: views and subqueries	5
-i, --infile	string	Input file (IQL file) from which queries are read	{stdin}
-q, --iqldata	string	Context (data) file for templating (json or jsonnet file)
--loglevel	string	Log level, must be one of fatal	fatal
--mcp.config	string	JSON / YAML configuration object for the MCP server (stackql mcp and stackql srv)	{}
--mcp.log.format	string	MCP audit log encoding, jsonl or otel (OTLP/JSON log records); overrides server.audit.format in --mcp.config. See Log format. Available in StackQL releases from v0.11.660.	jsonl
--mcp.protocol.version	string	Newest MCP protocol revision advertised, auto, 2026-07-28 (sessionless only) or an older revision such as 2025-11-25; overrides server.protocol_version in --mcp.config. See Pinning the revision. Available in StackQL releases from v0.12.732.	auto
--mcp.server.type	string	MCP server type, one of reverse_proxy. See MCP server type.	http
--metadatattl	integer	TTL for cached metadata documents, in seconds	3600
--namespaces	string	JSON / YAML string representing namespaces for caching, views etc	{}
--offline	flag	Work offline, using cached data	false
-f, --outfile	string	Output file into which results are written	{stdout}
-o, --output	string	Output format, must be one of otel (ndjson is accepted as an alias for jsonl). otel emits OpenTelemetry log records, see Output Modes; available in StackQL releases from v0.11.660. With an exporter configured in --otel.config, otel records are also pushed to that endpoint	table
--otel.config	string	JSON / YAML string configuring the otel output format; exporter.endpoint, exporter.headers, exporter.timeout_ms and exporter.batch_size push the records to an OTLP/HTTP logs endpoint, see Pushing to an OTLP endpoint. Available in StackQL releases from v0.12.732	{}
--preview	string	JSON string enabling preview functionality. {"unstable": true} exposes the document-driven stackql_unstable_<provider>.<service>.<resource> relations, which are resolved and run by omnisdk straight from the provider documents with rows streamed as they are produced; the remaining keys (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) tune that backend. Preview functionality is not stable: behaviour, syntax and output may change or break between releases without notice, so do not rely on it in production. From v1.0 the same opt-in exposes the stackql_preview.iac.run and stackql_preview.iac.destroy relations, which apply and tear down a declared resource set through omnisdk with state kept under the application root. See Preview functionality	{}
--querycachesize	integer	Size in number of entries of LRU cache for query plans	10000
--registry	string	JSON / YAML string configuring the provider registry location and provider document signature verification	see --registry
--session	string	JSON / YAML string representing session config	{}
--sqlBackend	string	JSON / YAML string representing SQL Backend System Config	see --sqlBackend
--store.txn	string	JSON / YAML string representing Txn store config	{}
--tls.CABundle	string	Path to CA bundle, if not specified then system defaults used
--tls.allowInsecure	flag	Allow trust of insecure certificates (not recommended)
--var	string	External variables provided as key/value pairs for sourcing into StackQL queries through jsonnet data files
-v, --verbose	flag	Verbose output	false
-h, --help		Context specific help for stackql
--version		Displays the version of the StackQL program

--registry

The --registry flag configures where provider documents are read from and whether their signatures are verified. The value is a JSON string with the following keys:

Key	Description	Default
url	Registry URL. The public StackQL provider registry is used when omitted.	public registry
localDocRoot	A local directory holding provider documents, read in place of downloading from the registry. Used when developing a provider.
srcPrefix	Path prefix under the registry root where provider source documents live.	src
verifyConfig.nopVerify	true skips signature verification. Set to false to require an embedded ML-DSA-65 (FIPS 204) signature on every provider and service document read, including the document-backed preview relations.	true
verifyConfig.publicKeys	A JSON object mapping key IDs to hex-encoded ML-DSA-65 public keys, for private registries. It replaces the embedded production keys; an explicit empty object is an error.	embedded keys

Example: Require signed provider documents

Turns verification on for every provider and service document read from the public registry, checked against the embedded production keys:

stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell

Example: Read unsigned documents from a local directory

Points the registry at a directory of provider documents under development. Those documents are unsigned, so verification stays off:

stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell

note

Signature verification is available in StackQL releases from v1.0 and is off by default. Signatures cover the exact YAML bytes of a document, so any edit, including a formatting or newline change, invalidates them; re-sign with the registry's pqsig sign-doc tool. Unsigned local development documents must keep nopVerify: true. The former certificate options and .sig sidecar files are no longer used, and archives published with sidecars only must be republished before verified use. Verification authenticates documents when they are read; archive download and extraction are not covered.

--sqlBackend

The --sqlBackend flag configures an external SQL backend for StackQL, allowing you to use an external database engine (such as PostgreSQL) instead of the default embedded SQL engine. This is useful for leveraging an external database for query processing, persistent storage, or integration with existing database infrastructure.

The value is a JSON string with the following keys:

Key	Description	Example Values
dbEngine	The database engine type	postgres_tcp
sqlDialect	The SQL dialect to use	postgres
dsn	The data source name (connection string) for the database	See examples below

Example: Using a PostgreSQL Backend

./stackql \
  --sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
  shell

Example: Using Databricks PostgreSQL Interface

Databricks exposes a PostgreSQL-compatible interface that can be used as a StackQL SQL backend. The DSN uses the standard PostgreSQL connection string format with your Databricks credentials:

./stackql \
  --sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
  shell

note

Special characters in the username or password (such as @) must be URL-encoded in the DSN (e.g., @ becomes %40).