# Global Flags

> Global flags for the stackql binary: authentication, output format, registry location, logging and SQL backend settings, available on every command.

Source: https://stackql.io/command-line-usage/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`](/getting-started/using-stackql#the-stackqlrc-initialization-file)) file.  Flags include:  

| Flag | Data Type | Description | Default |
| -- | -- | -- | -- |
| `--acid` | string | JSON / YAML string representing ACID config | `{}` |
| `--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`](/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` |
| `--mcp.config` | string | JSON / YAML configuration object for the [MCP server](/command-line-usage/mcp#mcp-configuration-object) (`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](/command-line-usage/mcp#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](/command-line-usage/mcp#pinning-the-revision).  Available in StackQL releases from `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | MCP server type, one of .  See [MCP server type](/command-line-usage/mcp#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  (`ndjson` is accepted as an alias for `jsonl`).  `otel` emits OpenTelemetry log records, see [Output Modes](/getting-started/output-modes#otel-output); 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](/getting-started/output-modes#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.  See [Preview functionality](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--querycachesize` | integer | Size in number of entries of LRU cache for query plans | `10000` |
| `--registry` | string | openapi registry context keyvals in json form |  |
| `--session` | string | JSON / YAML string representing session config | `{}` |
| `--sqlBackend` | string | JSON / YAML string representing SQL Backend System Config | see [`--sqlBackend`](#--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 | |

## `--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

```bash
./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:

```bash
./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`).
:::