# Flag global

> Flag global untuk biner stackql: autentikasi, format output, lokasi registri, log, dan pengaturan backend SQL, yang tersedia di setiap perintah.

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

Flag global menentukan perilaku program saat runtime untuk aplikasi StackQL; flag ini ditetapkan di baris perintah saat aplikasi StackQL dijalankan (dalam mode interaktif/shell atau mode exec non-interaktif) atau diambil dari file inisialisasi StackQL ([`.stackqlrc`](/getting-started/using-stackql#the-stackqlrc-initialization-file)).  Flag yang tersedia meliputi:  

| Flag | Tipe data | Deskripsi | Default |
| -- | -- | -- | -- |
| `--access.config` | string | Konfigurasi akses pemanggil, objek pembungkus JSON `{"path": "/path/to/access.json"}` (jalur file biasa juga diterima).  Mengaktifkan [manajemen akses](/command-line-usage/access-management): pemanggil diautentikasi dengan JWT, token bearer statis, TLS mutual, atau identitas OS lokal, dan pernyataan diotorisasi berdasarkan aturan kebijakan.  Kredensial token lokal dibaca dari `STACKQL_CALLER_TOKEN`.  Tersedia mulai StackQL `v1.0`. | |
| `--acid` | string | String JSON / YAML yang merepresentasikan konfigurasi ACID | `{}` |
| `--allow-persistent-secrets` | flag | Mengizinkan sesi memilih penyimpanan rahasia OS persisten (macOS Keychain, Linux Secret Service, atau Windows Credential Manager) dengan `SET "$.secret_store"`.  Penyimpanan berbasis file datar tetap ditolak meskipun flag ini digunakan.  Lihat [Sesi provider dan rahasia](/getting-started/provider-sessions#persistent-os-secret-stores).  Tersedia mulai StackQL `v1.0`. | `false` |
| `--allow-secret-dereference` | flag | Mengizinkan nilai rahasia dan kredensial didereferensi dalam ekspresi SQL (`"$secrets.name"`, `"$auth.provider.field"`), dengan konsekuensi nilai tersebut dapat masuk ke hasil, log, dan artefak kueri yang disimpan.  Tidak diperlukan untuk autentikasi provider biasa.  Lihat [Nilai rahasia di SQL](/getting-started/provider-sessions#secret-values-in-sql).  Tersedia mulai StackQL `v1.0`. | `false` |
| `--apirequesttimeout` | integer | Batas waktu permintaan API dalam detik, 0 berarti tanpa batas waktu | `45` |
| `--approot` | string | Jalur root konfigurasi dan cache aplikasi | `{cwd}/.stackql` |
| `--approotfilemode` | uint32 | Mode file konfigurasi dan cache aplikasi | `493` |
| `--auth` | string | Pasangan kunci-nilai konteks `auth` dalam bentuk json |  |
| `--cachekeycount` | integer | Jumlah kunci awal cache | `100` |
| `--configfile` | string | Jalur lengkap file konfigurasi | `{cwd}/.stackqlrc` |
| `--cpuprofile` | string | File `cpuprofile`, tidak ada jika kosong | `null` |
| `--dataflow.dependency.max` | int | Kedalaman maksimum dependensi dataflow untuk kueri tertentu | `50` |
| `--dataflow.components.max` | int | Jumlah maksimum komponen dataflow yang terhubung lemah untuk kueri tertentu | `50` |
| `--dbInternal` | string | String JSON / YAML untuk mengonfigurasi penanganan kueri pemeliharaan DBMS | `{}` |
| `-d`, `--delimiter` | string | Pembatas untuk output csv. Hanya satu karakter.  Diabaikan untuk semua output selain csv | `,` |
| `--dryrun` | flag | Flag `dryrun`; hanya menjalankan praprosesor, output hasil template akan dikembalikan | `false` |
| `--env.file` | string | File opsional bergaya dotenv yang dimuat ke lingkungan proses saat startup (semua perintah); alat MCP [`reload_credentials`](/mcp/reload_credentials) memuatnya ulang sesuai permintaan. File yang tidak ada ditoleransi; kunci dengan nilai kosong dilewati; variabel yang sudah ada diganti. Tidak dimuat dari `.stackqlrc`. Tersedia di rilis StackQL setelah `v0.10.542`. | `null` |
| `--execution.concurrency.limit` | int | Batas konkurensi untuk eksekusi kueri | `1` |
| `--export.alias` | string | Prefiks alias ekspor (namespace atau skema) | |
| `--gc` | string | String JSON / YAML yang merepresentasikan konfigurasi GC | `{}` |
| `-H`, `--hideheaders` | flag | Menonaktifkan header kolom, hanya valid dengan `--output csv` atau `--output text` | `false` |
| `--http.log.enabled` | flag | Menampilkan info permintaan http di terminal | `false` |
| `--http.proxy.host` | string | Host proxy (kosongkan jika tanpa proxy) | `null` |
| `--http.proxy.password` | string | Kata sandi proxy | `null` |
| `--http.proxy.port` | integer | Port proxy, angka apa pun yang kurang dari atau sama dengan 0 akan menghasilkan port default untuk skema tertentu (misalnya `http -> 80`) | `-1` |
| `--http.proxy.scheme` | string | Skema proxy, `http` atau `https` | `http` |
| `--http.proxy.user` | string | Pengguna proxy | `null` |
| `--http.response.maxResults` | integer | Jumlah hasil maksimum per permintaan http, angka apa pun yang kurang dari atau sama dengan 0 berarti tanpa batasan | `-1` |
| `--http.response.pageLimit` | integer | Jumlah halaman hasil maksimum yang akan dikembalikan per sumber daya, angka apa pun yang kurang dari atau sama dengan 0 berarti tanpa batasan | `20` |
| `--indirect.depth.max` | integer | Kedalaman maksimum untuk kueri tidak langsung: tampilan dan subkueri | `5` |
| `-i`, `--infile` | string | File input (file IQL) tempat kueri dibaca | `{stdin}` |
| `-q`, `--iqldata` | string | File konteks (data) untuk penggunaan template (file `json` atau `jsonnet`)| |
| `--loglevel` | string | Level log, harus salah satu dari  | `fatal` |
| `--mcp.config` | string | Objek konfigurasi JSON / YAML untuk [server MCP](/command-line-usage/mcp#mcp-configuration-object) (`stackql mcp` dan `stackql srv`) | `{}` |
| `--mcp.log.format` | string | Pengodean log audit MCP, `jsonl` atau `otel` (catatan log OTLP/JSON); mengganti `server.audit.format` di `--mcp.config`.  Lihat [Format log](/command-line-usage/mcp#log-format).  Tersedia mulai StackQL `v0.11.660`. | `jsonl` |
| `--mcp.protocol.version` | string | Revisi protokol MCP terbaru yang dinyatakan, `auto`, `2026-07-28` (hanya tanpa sesi), atau revisi yang lebih lama seperti `2025-11-25`; mengganti `server.protocol_version` di `--mcp.config`.  Lihat [Mengunci revisi](/command-line-usage/mcp#pinning-the-revision).  Tersedia mulai StackQL `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | Tipe server MCP, salah satu dari .  Lihat [Tipe server MCP](/command-line-usage/mcp#mcp-server-type). | `http` |
| `--metadatattl` | integer | TTL untuk dokumen metadata dalam cache, dalam detik | `3600` |
| `--namespaces` | string | String JSON / YAML yang merepresentasikan namespace untuk cache, tampilan, dan sebagainya | `{}` |
| `--offline` | flag | Bekerja secara offline menggunakan data cache | `false` |
| `-f`, `--outfile` | string | File output tempat hasil ditulis | `{stdout}` |
| `-o`, `--output` | string | Format output, harus salah satu dari  (`ndjson` diterima sebagai alias untuk `jsonl`).  `otel` menghasilkan catatan log OpenTelemetry, lihat [Mode output](/getting-started/output-modes#otel-output); tersedia mulai StackQL `v0.11.660`.  Dengan exporter yang dikonfigurasi di `--otel.config`, catatan `otel` juga dikirim ke endpoint tersebut | `table` |
| `--otel.config` | string | String JSON / YAML yang mengonfigurasi format output `otel`; `exporter.endpoint`, `exporter.headers`, `exporter.timeout_ms`, dan `exporter.batch_size` mengirim catatan ke endpoint log OTLP/HTTP, lihat [Mengirim langsung ke endpoint OTLP](/getting-started/output-modes#pushing-to-an-otlp-endpoint).  Tersedia mulai StackQL `v0.12.732` | `{}` |
| `--preview` | string | String JSON yang mengaktifkan fungsionalitas pratinjau.  `{"unstable": true}` mengekspos relasi `stackql_unstable_<provider>.<service>.<resource>` berbasis dokumen, yang diselesaikan dan dijalankan oleh `omnisdk` langsung dari dokumen provider dengan baris yang dialirkan segera setelah dihasilkan; kunci lainnya (`batchSize`, `flushInterval`, `endpoint`, `insecureSkipTLSVerify`) menyesuaikan backend tersebut.  Fungsionalitas pratinjau tidak stabil: perilaku, sintaksis, dan output dapat berubah atau rusak di antara rilis tanpa pemberitahuan, jadi jangan mengandalkannya di lingkungan produksi.  Mulai `v1.0`, aktivasi eksplisit yang sama mengekspos relasi `stackql_preview.iac.run` dan `stackql_preview.iac.destroy`, yang menerapkan dan menghapus kumpulan sumber daya yang dideklarasikan melalui `omnisdk` dengan status yang disimpan di bawah root aplikasi.  Lihat [Fungsionalitas pratinjau](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--querycachesize` | integer | Ukuran cache LRU untuk rencana kueri, dalam jumlah entri | `10000` |
| `--registry` | string | String JSON / YAML yang mengonfigurasi lokasi registri provider dan verifikasi tanda tangan dokumen provider | lihat [`--registry`](#--registry) |
| `--session` | string | String JSON / YAML yang merepresentasikan konfigurasi sesi | `{}` |
| `--sqlBackend` | string | String JSON / YAML yang merepresentasikan konfigurasi sistem backend SQL | lihat [`--sqlBackend`](#--sqlbackend) |
| `--store.txn` | string | String JSON / YAML yang merepresentasikan konfigurasi penyimpanan Txn | `{}` |
| `--tls.CABundle` | string | Jalur ke bundle CA; jika tidak ditentukan, default sistem akan digunakan |  |
| `--tls.allowInsecure` | flag | Mengizinkan kepercayaan terhadap sertifikat yang tidak aman (tidak disarankan) |  |
| `--var` | string | Variabel eksternal yang diberikan sebagai pasangan kunci/nilai untuk dimasukkan ke kueri StackQL melalui file data `jsonnet` |  |
| `-v`, `--verbose` | flag | Output verbose | `false` |
| `-h`, `--help` | | Bantuan sesuai konteks untuk stackql | |
| `--version` | | Menampilkan versi program StackQL | |

## `--registry`

Flag `--registry` mengonfigurasi dari mana dokumen provider dibaca dan apakah tanda tangannya diverifikasi.  Nilainya berupa string JSON dengan kunci berikut:

| Kunci | Deskripsi | Default |
| -- | -- | -- |
| `url` | URL registri.  Registri provider StackQL publik digunakan jika tidak ditentukan. | registri publik |
| `localDocRoot` | Direktori lokal yang berisi dokumen provider, yang dibaca sebagai pengganti pengunduhan dari registri.  Digunakan saat [mengembangkan provider](/developers/developing-stackql-providers#testing-a-provider-locally). | |
| `srcPrefix` | Prefiks jalur di bawah root registri tempat dokumen sumber provider berada. | `src` |
| `verifyConfig.nopVerify` | `true` melewati verifikasi tanda tangan.  Tetapkan ke `false` untuk mewajibkan tanda tangan ML-DSA-65 (FIPS 204) tersemat pada setiap dokumen provider dan layanan yang dibaca, termasuk relasi pratinjau berbasis dokumen. | `true` |
| `verifyConfig.publicKeys` | Objek JSON yang memetakan ID kunci ke kunci publik ML-DSA-65 yang dikodekan hex, untuk registri privat.  Objek ini menggantikan kunci produksi tersemat; objek kosong yang eksplisit merupakan error. | kunci tersemat |

### Contoh: mewajibkan dokumen provider yang ditandatangani

Mengaktifkan verifikasi untuk setiap dokumen provider dan layanan yang dibaca dari registri publik, yang diperiksa terhadap kunci produksi tersemat:

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

### Contoh: membaca dokumen tanpa tanda tangan dari direktori lokal

Mengarahkan registri ke direktori berisi dokumen provider yang sedang dikembangkan.  Dokumen tersebut tidak ditandatangani, sehingga verifikasi tetap nonaktif:

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

:::note

Verifikasi tanda tangan tersedia mulai StackQL `v1.0` dan nonaktif secara default.  Tanda tangan mencakup byte YAML yang persis dari sebuah dokumen, sehingga setiap pengeditan, termasuk perubahan format atau baris baru, membuat tanda tangan tidak valid; tandatangani ulang dengan alat `pqsig sign-doc` milik registri.  Dokumen pengembangan lokal yang tidak ditandatangani harus tetap menggunakan `nopVerify: true`.  Opsi sertifikat sebelumnya dan file sidecar `.sig` tidak lagi digunakan, dan arsip yang dipublikasikan hanya dengan sidecar harus dipublikasikan ulang sebelum digunakan dengan verifikasi.  Verifikasi mengautentikasi dokumen saat dokumen dibaca; pengunduhan dan ekstraksi arsip tidak tercakup.

:::

## `--sqlBackend`

Flag `--sqlBackend` mengonfigurasi backend SQL eksternal untuk StackQL, sehingga Anda dapat menggunakan mesin database eksternal (seperti PostgreSQL) sebagai pengganti mesin SQL tersemat default. Ini berguna untuk memanfaatkan database eksternal untuk pemrosesan kueri, penyimpanan persisten, atau integrasi dengan infrastruktur database yang sudah ada.

Nilainya berupa string JSON dengan kunci berikut:

| Kunci | Deskripsi | Contoh nilai |
| -- | -- | -- |
| `dbEngine` | Tipe mesin database | `postgres_tcp` |
| `sqlDialect` | Dialek SQL yang digunakan | `postgres` |
| `dsn` | Nama sumber data (string koneksi) untuk database | Lihat contoh di bawah |

### Contoh: menggunakan backend PostgreSQL

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

### Contoh: menggunakan antarmuka PostgreSQL Databricks

Databricks menyediakan antarmuka yang kompatibel dengan PostgreSQL yang dapat digunakan sebagai backend SQL StackQL. DSN menggunakan format string koneksi PostgreSQL standar dengan kredensial Databricks Anda:

```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
Karakter khusus dalam nama pengguna atau kata sandi (seperti `@`) harus dikodekan URL di DSN (misalnya, `@` menjadi `%40`).
:::
