# Globale Flags

> Globale Flags der stackql-Binärdatei: Einstellungen für Authentifizierung, Ausgabeformat, Registry-Speicherort, Logging und SQL-Backend, verfügbar bei jedem Befehl.

Source: https://stackql.io/de/command-line-usage/global-flags

Globale Flags legen das Laufzeitverhalten der StackQL-Anwendung fest; diese Flags werden auf der Kommandozeile beim Start der StackQL-Anwendung gesetzt (entweder im interaktiven Shell-Modus oder im nicht interaktiven exec-Modus) oder aus der StackQL-Initialisierungsdatei ([`.stackqlrc`](/getting-started/using-stackql#the-stackqlrc-initialization-file)) gelesen.  Die Flags umfassen:  

| Flag | Datentyp | Beschreibung | Standard |
| -- | -- | -- | -- |
| `--access.config` | string | Konfiguration des Aufruferzugriffs, ein JSON-Envelope `{"path": "/path/to/access.json"}` (ein bloßer Dateipfad wird ebenfalls akzeptiert).  Aktiviert die [Zugriffsverwaltung](/command-line-usage/access-management): Aufrufer werden per JWT, statischem Bearer-Token, Mutual TLS oder lokaler OS-Identität authentifiziert und Anweisungen anhand von Policy-Regeln autorisiert.  Lokale Token-Anmeldedaten werden aus `STACKQL_CALLER_TOKEN` gelesen.  Verfügbar in StackQL-Releases ab `v1.0`. | |
| `--acid` | string | JSON-/YAML-String mit der ACID-Konfiguration | `{}` |
| `--allow-persistent-secrets` | flag | Erlaubt einer Sitzung, mit `SET "$.secret_store"` einen persistenten OS-Secret-Store (macOS Keychain, Linux Secret Service oder Windows Credential Manager) auszuwählen.  Flat-File-Stores werden auch mit dem Flag verweigert.  Siehe [Provider-Sitzungen und Secrets](/getting-started/provider-sessions#persistent-os-secret-stores).  Verfügbar in StackQL-Releases ab `v1.0`. | `false` |
| `--allow-secret-dereference` | flag | Erlaubt das Dereferenzieren von Secret- und Anmeldedatenwerten in SQL-Ausdrücken (`"$secrets.name"`, `"$auth.provider.field"`), mit der Folge, dass sie in Ergebnisse, Logs und persistierte Abfrageartefakte gelangen können.  Für die normale Provider-Authentifizierung nicht erforderlich.  Siehe [Secret-Werte in SQL](/getting-started/provider-sessions#secret-values-in-sql).  Verfügbar in StackQL-Releases ab `v1.0`. | `false` |
| `--apirequesttimeout` | integer | Timeout für API-Anfragen in Sekunden, 0 für kein Timeout | `45` |
| `--approot` | string | Wurzelpfad für Anwendungskonfiguration und Cache | `{cwd}/.stackql` |
| `--approotfilemode` | uint32 | Dateimodus für Anwendungskonfiguration und Cache | `493` |
| `--auth` | string | `auth`-Kontext-Schlüssel-Wert-Paare in json-Form |  |
| `--cachekeycount` | integer | Anfängliche Schlüsselanzahl des Caches | `100` |
| `--configfile` | string | Vollständiger Pfad der Konfigurationsdatei | `{cwd}/.stackqlrc` |
| `--cpuprofile` | string | `cpuprofile`-Datei, keine wenn leer | `null` |
| `--dataflow.dependency.max` | int | Maximale Tiefe der Datenflussabhängigkeiten für eine Abfrage | `50` |
| `--dataflow.components.max` | int | Maximale Anzahl schwach zusammenhängender Datenflusskomponenten für eine Abfrage | `50` |
| `--dbInternal` | string | JSON-/YAML-String zur Konfiguration der Behandlung von DBMS-Housekeeping-Abfragen | `{}` |
| `-d`, `--delimiter` | string | Trennzeichen für die csv-Ausgabe. Nur ein einzelnes Zeichen.  Wird bei jeder Nicht-csv-Ausgabe ignoriert | `,` |
| `--dryrun` | flag | `dryrun`-Flag; nur den Präprozessor ausführen, die templatierte Ausgabe wird zurückgegeben | `false` |
| `--env.file` | string | Optionale Datei im dotenv-Stil, die beim Start in die Prozessumgebung eingelesen wird (alle Befehle); das MCP-Tool [`reload_credentials`](/mcp/reload_credentials) liest sie bei Bedarf erneut ein. Eine fehlende Datei wird toleriert; Schlüssel mit leeren Werten werden übersprungen; vorhandene Variablen werden überschrieben. Wird nicht aus `.stackqlrc` gelesen. Verfügbar in StackQL-Releases nach `v0.10.542`. | `null` |
| `--execution.concurrency.limit` | int | Parallelitätslimit für die Abfrageausführung | `1` |
| `--export.alias` | string | Präfix für Export-Aliase (Namespace oder Schema) | |
| `--gc` | string | JSON-/YAML-String mit der GC-Konfiguration | `{}` |
| `-H`, `--hideheaders` | flag | Deaktiviert Spaltenüberschriften, nur gültig mit `--output csv` oder `--output text` | `false` |
| `--http.log.enabled` | flag | Zeigt http-Anfrageinformationen im Terminal an | `false` |
| `--http.proxy.host` | string | Proxy-Host (leer lassen für keinen Proxy) | `null` |
| `--http.proxy.password` | string | Proxy-Passwort | `null` |
| `--http.proxy.port` | integer | Proxy-Port, jede Zahl kleiner oder gleich 0 führt zum Standardport des jeweiligen Schemas (z. B. `http -> 80`) | `-1` |
| `--http.proxy.scheme` | string | Proxy-Schema, `http` oder `https` | `http` |
| `--http.proxy.user` | string | Proxy-Benutzer | `null` |
| `--http.response.maxResults` | integer | Maximale Ergebnisse pro http-Anfrage, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung | `-1` |
| `--http.response.pageLimit` | integer | Maximale Anzahl von Ergebnisseiten, die pro Ressource zurückgegeben werden, jede Zahl kleiner oder gleich 0 bedeutet keine Begrenzung | `20` |
| `--indirect.depth.max` | integer | Maximale Tiefe für indirekte Abfragen: Views und Unterabfragen | `5` |
| `-i`, `--infile` | string | Eingabedatei (IQL-Datei), aus der Abfragen gelesen werden | `{stdin}` |
| `-q`, `--iqldata` | string | Kontextdatei (Daten) für das Templating (`json`- oder `jsonnet`-Datei)| |
| `--loglevel` | string | Log-Level, muss einer von  sein | `fatal` |
| `--mcp.config` | string | JSON-/YAML-Konfigurationsobjekt für den [MCP-Server](/command-line-usage/mcp#mcp-configuration-object) (`stackql mcp` und `stackql srv`) | `{}` |
| `--mcp.log.format` | string | Kodierung des MCP-Audit-Logs, `jsonl` oder `otel` (OTLP/JSON-Log-Records); überschreibt `server.audit.format` in `--mcp.config`.  Siehe [Log-Format](/command-line-usage/mcp#log-format).  Verfügbar in StackQL-Releases ab `v0.11.660`. | `jsonl` |
| `--mcp.protocol.version` | string | Neueste angekündigte MCP-Protokollrevision, `auto`, `2026-07-28` (nur sitzungslos) oder eine ältere Revision wie `2025-11-25`; überschreibt `server.protocol_version` in `--mcp.config`.  Siehe [Revision festlegen](/command-line-usage/mcp#pinning-the-revision).  Verfügbar in StackQL-Releases ab `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | MCP-Servertyp, einer von .  Siehe [MCP-Servertyp](/command-line-usage/mcp#mcp-server-type). | `http` |
| `--metadatattl` | integer | TTL für zwischengespeicherte Metadatendokumente, in Sekunden | `3600` |
| `--namespaces` | string | JSON-/YAML-String mit Namespaces für Caching, Views usw. | `{}` |
| `--offline` | flag | Offline arbeiten, mit zwischengespeicherten Daten | `false` |
| `-f`, `--outfile` | string | Ausgabedatei, in die Ergebnisse geschrieben werden | `{stdout}` |
| `-o`, `--output` | string | Ausgabeformat, muss eines von  sein (`ndjson` wird als Alias für `jsonl` akzeptiert).  `otel` gibt OpenTelemetry-Log-Records aus, siehe [Ausgabemodi](/getting-started/output-modes#otel-output); verfügbar in StackQL-Releases ab `v0.11.660`.  Ist in `--otel.config` ein Exporter konfiguriert, werden `otel`-Records zusätzlich an diesen Endpunkt gesendet | `table` |
| `--otel.config` | string | JSON-/YAML-String zur Konfiguration des Ausgabeformats `otel`; `exporter.endpoint`, `exporter.headers`, `exporter.timeout_ms` und `exporter.batch_size` senden die Records an einen OTLP/HTTP-Logs-Endpunkt, siehe [An einen OTLP-Endpunkt senden](/getting-started/output-modes#pushing-to-an-otlp-endpoint).  Verfügbar in StackQL-Releases ab `v0.12.732` | `{}` |
| `--preview` | string | JSON-String zur Aktivierung von Preview-Funktionen.  `{"unstable": true}` stellt die dokumentgetriebenen Relationen `stackql_unstable_<provider>.<service>.<resource>` bereit, die von `omnisdk` direkt aus den Provider-Dokumenten aufgelöst und ausgeführt werden, wobei Zeilen gestreamt werden, sobald sie entstehen; die übrigen Schlüssel (`batchSize`, `flushInterval`, `endpoint`, `insecureSkipTLSVerify`) stimmen dieses Backend ab.  Preview-Funktionen sind nicht stabil: Verhalten, Syntax und Ausgabe können sich zwischen Releases ohne Ankündigung ändern oder brechen, verlassen Sie sich daher in der Produktion nicht darauf.  Ab `v1.0` stellt dasselbe Opt-in die Relationen `stackql_preview.iac.run` und `stackql_preview.iac.destroy` bereit, die eine deklarierte Ressourcenmenge über `omnisdk` anwenden und abbauen, wobei der Zustand unter dem Anwendungswurzelpfad gehalten wird.  Siehe [Preview-Funktionen](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--querycachesize` | integer | Größe des LRU-Caches für Abfragepläne in Anzahl der Einträge | `10000` |
| `--registry` | string | JSON-/YAML-String zur Konfiguration des Speicherorts der Provider-Registry und der Signaturprüfung von Provider-Dokumenten | siehe [`--registry`](#--registry) |
| `--session` | string | JSON-/YAML-String mit der Sitzungskonfiguration | `{}` |
| `--sqlBackend` | string | JSON-/YAML-String mit der Systemkonfiguration des SQL-Backends | siehe [`--sqlBackend`](#--sqlbackend) |
| `--store.txn` | string | JSON-/YAML-String mit der Konfiguration des Txn-Stores | `{}` |
| `--tls.CABundle` | string | Pfad zum CA-Bundle, ohne Angabe werden die Systemstandards verwendet |  |
| `--tls.allowInsecure` | flag | Erlaubt das Vertrauen in unsichere Zertifikate (nicht empfohlen) |  |
| `--var` | string | Externe Variablen als Schlüssel/Wert-Paare, die über `jsonnet`-Datendateien in StackQL-Abfragen eingelesen werden |  |
| `-v`, `--verbose` | flag | Ausführliche Ausgabe | `false` |
| `-h`, `--help` | | Kontextspezifische Hilfe für stackql | |
| `--version` | | Zeigt die Version des StackQL-Programms an | |

## `--registry`

Das Flag `--registry` konfiguriert, woher Provider-Dokumente gelesen werden und ob ihre Signaturen geprüft werden.  Der Wert ist ein JSON-String mit den folgenden Schlüsseln:

| Schlüssel | Beschreibung | Standard |
| -- | -- | -- |
| `url` | Registry-URL.  Ohne Angabe wird die öffentliche StackQL-Provider-Registry verwendet. | öffentliche Registry |
| `localDocRoot` | Ein lokales Verzeichnis mit Provider-Dokumenten, das anstelle eines Downloads aus der Registry gelesen wird.  Wird beim [Entwickeln eines Providers](/developers/developing-stackql-providers#testing-a-provider-locally) verwendet. | |
| `srcPrefix` | Pfadpräfix unterhalb der Registry-Wurzel, in dem die Provider-Quelldokumente liegen. | `src` |
| `verifyConfig.nopVerify` | `true` überspringt die Signaturprüfung.  Auf `false` setzen, um für jedes gelesene Provider- und Service-Dokument eine eingebettete ML-DSA-65-Signatur (FIPS 204) zu verlangen, einschließlich der dokumentgestützten Preview-Relationen. | `true` |
| `verifyConfig.publicKeys` | Ein JSON-Objekt, das Schlüssel-IDs auf hex-kodierte öffentliche ML-DSA-65-Schlüssel abbildet, für private Registries.  Es ersetzt die eingebetteten Produktionsschlüssel; ein explizit leeres Objekt ist ein Fehler. | eingebettete Schlüssel |

### Beispiel: Signierte Provider-Dokumente verlangen

Schaltet die Prüfung für jedes aus der öffentlichen Registry gelesene Provider- und Service-Dokument ein, geprüft gegen die eingebetteten Produktionsschlüssel:

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

### Beispiel: Unsignierte Dokumente aus einem lokalen Verzeichnis lesen

Verweist die Registry auf ein Verzeichnis mit Provider-Dokumenten in Entwicklung.  Diese Dokumente sind unsigniert, daher bleibt die Prüfung ausgeschaltet:

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

:::note

Die Signaturprüfung ist in StackQL-Releases ab `v1.0` verfügbar und standardmäßig ausgeschaltet.  Signaturen decken die exakten YAML-Bytes eines Dokuments ab, sodass jede Änderung, auch eine Formatierungs- oder Zeilenumbruchänderung, sie ungültig macht; signieren Sie mit dem Tool `pqsig sign-doc` der Registry neu.  Unsignierte lokale Entwicklungsdokumente müssen `nopVerify: true` beibehalten.  Die früheren Zertifikatsoptionen und `.sig`-Sidecar-Dateien werden nicht mehr verwendet, und Archive, die nur mit Sidecars veröffentlicht wurden, müssen vor einer geprüften Verwendung neu veröffentlicht werden.  Die Prüfung authentifiziert Dokumente beim Lesen; Download und Entpacken von Archiven sind nicht abgedeckt.

:::

## `--sqlBackend`

Das Flag `--sqlBackend` konfiguriert ein externes SQL-Backend für StackQL, sodass Sie anstelle der standardmäßig eingebetteten SQL-Engine eine externe Datenbank-Engine (etwa PostgreSQL) verwenden können. Das ist nützlich, um eine externe Datenbank für die Abfrageverarbeitung, persistente Speicherung oder die Integration in bestehende Datenbankinfrastruktur zu nutzen.

Der Wert ist ein JSON-String mit den folgenden Schlüsseln:

| Schlüssel | Beschreibung | Beispielwerte |
| -- | -- | -- |
| `dbEngine` | Der Typ der Datenbank-Engine | `postgres_tcp` |
| `sqlDialect` | Der zu verwendende SQL-Dialekt | `postgres` |
| `dsn` | Der Data Source Name (Verbindungszeichenfolge) der Datenbank | Siehe Beispiele unten |

### Beispiel: Ein PostgreSQL-Backend verwenden

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

### Beispiel: Die PostgreSQL-Schnittstelle von Databricks verwenden

Databricks stellt eine PostgreSQL-kompatible Schnittstelle bereit, die als StackQL-SQL-Backend verwendet werden kann. Der DSN verwendet das Standardformat der PostgreSQL-Verbindungszeichenfolge mit Ihren Databricks-Anmeldedaten:

```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
Sonderzeichen im Benutzernamen oder Passwort (etwa `@`) müssen im DSN URL-kodiert sein (z. B. wird aus `@` `%40`).
:::