# Глобальні прапорці

> Глобальні прапорці двійкового файлу stackql: автентифікація, формат виводу, розташування реєстру, журналювання та налаштування бекенду SQL, доступні для кожної команди.

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

Команди StackQL приймають глобальні прапорці, але деякі з них діють лише в певному режимі. Вказуйте їх у командному рядку або, де це підтримується, у файлі ініціалізації StackQL ([`.stackqlrc`](/getting-started/using-stackql#the-stackqlrc-initialization-file)). Прапорці `--pgsrv.*` перелічено в розділі [Параметри сервера PostgreSQL](/command-line-usage/srv#server-options).

| Прапорець | Тип даних | Опис | За замовчуванням |
| -- | -- | -- | -- |
| `--access.config` | string | Конфігурація доступу сторін, що викликають, у вигляді обгортки JSON `{"path": "/path/to/access.json"}` (простий шлях до файлу також приймається). Вмикає [керування доступом](/command-line-usage/access-management): сторони, що викликають, автентифікуються за JWT, статичним токеном bearer, взаємним TLS або ідентичністю локальної ОС, а інструкції авторизуються за правилами політики. Локальні облікові дані у вигляді токенів зчитуються з `STACKQL_CALLER_TOKEN`. Доступно в StackQL `v1.0` і новіших версіях. | |
| `--allow-persistent-secrets` | flag | Дозволяє сеансу вибрати постійне сховище секретів ОС (macOS Keychain, Linux Secret Service або Windows Credential Manager) за допомогою `SET "$.secret_store"`. Сховища у вигляді простих файлів відхиляються навіть із цим прапорцем. Див. [Сеанси провайдерів і секрети](/getting-started/provider-sessions#persistent-os-secret-stores). Доступно в StackQL `v1.0` і новіших версіях. | `false` |
| `--allow-secret-dereference` | flag | Дозволяє розіменування значень секретів і облікових даних у виразах SQL (`"$secrets.name"`, `"$auth.provider.field"`), унаслідок чого вони можуть потрапити в результати, журнали та збережені артефакти запитів. Не потрібен для звичайної автентифікації провайдерів. Див. [Значення секретів у SQL](/getting-started/provider-sessions#secret-values-in-sql). Доступно в StackQL `v1.0` і новіших версіях. | `false` |
| `--apirequesttimeout` | integer | Час очікування запиту до API в секундах, 0 - без обмеження часу очікування | `45` |
| `--approot` | string | Кореневий шлях для конфігурації та кешу застосунку | `{cwd}/.stackql` |
| `--approotfilemode` | uint32 | Режим файлів конфігурації та кешу застосунку | `493` |
| `--auth` | string | Пари "ключ-значення" контексту `auth` у форматі json |  |
| `--cachekeycount` | integer | Початкова кількість ключів кешу | `100` |
| `--configfile` | string | Повний шлях до файлу конфігурації | `{cwd}/.stackqlrc` |
| `--cpuprofile` | string | Файл `cpuprofile`; якщо порожньо, не використовується | `null` |
| `--dataflow.dependency.max` | int | Максимальна глибина залежностей потоку даних для одного запиту | `50` |
| `--dataflow.components.max` | int | Максимальна кількість слабко зв'язних компонентів потоку даних для одного запиту | `50` |
| `--dbInternal` | string | Рядок JSON / YAML для налаштування обробки службових запитів СКБД | `{}` |
| `-d`, `--delimiter` | string | Роздільник для виводу csv. Лише один символ. Ігнорується для всіх форматів виводу, крім csv | `,` |
| `--dryrun` | flag | Прапорець `dryrun`; виконується лише препроцесор, повертається вивід, сформований із шаблону | `false` |
| `--env.file` | string | Необов'язковий файл у стилі dotenv, який завантажується в середовище процесу під час запуску (для всіх команд); інструмент MCP [`reload_credentials`](/mcp/reload_credentials) повторно завантажує його на вимогу. Відсутність файлу допускається; ключі з порожніми значеннями пропускаються; наявні змінні перезаписуються. Не зчитується з `.stackqlrc`. Доступно у випусках StackQL після `v0.10.542`. | `null` |
| `--execution.concurrency.limit` | int | Обмеження паралельності під час виконання запитів | `1` |
| `--export.alias` | string | Префікс псевдоніма експорту (простір імен або схема) | |
| `--gc` | string | Рядок JSON / YAML з конфігурацією GC | `{}` |
| `-H`, `--hideheaders` | flag | Вимикає заголовки стовпців, діє лише з `--output csv` або `--output text` | `false` |
| `--http.log.enabled` | flag | Відображати відомості про запити HTTP у терміналі | `false` |
| `--http.proxy.host` | string | Хост проксі (залиште порожнім, щоб не використовувати проксі) | `null` |
| `--http.proxy.password` | string | Пароль проксі | `null` |
| `--http.proxy.port` | integer | Порт проксі; будь-яке число, що не перевищує 0, означає порт за замовчуванням для відповідної схеми (наприклад, `http -> 80`) | `-1` |
| `--http.proxy.scheme` | string | Схема проксі, `http` або `https` | `http` |
| `--http.proxy.user` | string | Користувач проксі | `null` |
| `--http.response.maxResults` | integer | Максимальна кількість результатів на один запит HTTP; будь-яке число, що не перевищує 0, означає відсутність обмеження | `-1` |
| `--http.response.pageLimit` | integer | Максимальна кількість сторінок результатів, що повертаються для одного ресурсу; будь-яке число, що не перевищує 0, означає відсутність обмеження | `20` |
| `--indirect.depth.max` | integer | Максимальна глибина непрямих запитів: подань і підзапитів | `5` |
| `-i`, `--infile` | string | Вхідний файл (файл IQL), з якого зчитуються запити | `{stdin}` |
| `-q`, `--iqldata` | string | Файл контексту (даних) для шаблонізації (файл `json` або `jsonnet`)| |
| `--loglevel` | string | Рівень журналювання, має бути одним із \{`panic`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`\} (`warning` приймається як псевдонім для `warn`) | `fatal` |
| `--mcp.config` | string | Об'єкт конфігурації JSON / YAML для [сервера MCP](/command-line-usage/mcp#mcp-configuration-object) (`stackql mcp` і `stackql srv`) | `{}` |
| `--mcp.log.format` | string | Кодування журналу аудиту MCP, `jsonl` або `otel` (записи журналу OTLP/JSON); перевизначає `server.audit.format` у `--mcp.config`. Див. [Формат журналу](/command-line-usage/mcp#log-format). Доступно в StackQL `v0.11.660` і новіших версіях. | `jsonl` |
| `--mcp.protocol.version` | string | Найновіша ревізія протоколу MCP, яку оголошує сервер: `auto`, `2026-07-28` (лише в режимі без сеансу) або старіша ревізія, наприклад `2025-11-25`; перевизначає `server.protocol_version` у `--mcp.config`. Див. [Закріплення ревізії](/command-line-usage/mcp#pinning-the-revision). Доступно в StackQL `v0.12.732` і новіших версіях. | `auto` |
| `--mcp.server.type` | string | Тип сервера MCP, одне зі значень \{`http`, `stdio`, `reverse_proxy`\}. Див. [Тип сервера MCP](/command-line-usage/mcp#mcp-server-type). | `http` |
| `--metadatattl` | integer | TTL кешованих документів метаданих, у секундах | `3600` |
| `--namespaces` | string | Рядок JSON / YAML, що описує простори імен для кешування, подань тощо | `{}` |
| `--offline` | flag | Працювати офлайн, використовуючи кешовані дані | `false` |
| `-f`, `--outfile` | string | Файл виводу, у який записуються результати | `{stdout}` |
| `-o`, `--output` | string | Формат виводу, має бути одним із \{`json`, `jsonl`, `table`, `csv`, `text`, `otel`\} (`ndjson` приймається як псевдонім для `jsonl`). Формат `otel` видає записи журналу OpenTelemetry, див. [Режими виводу](/getting-started/output-modes#otel-output); доступно в StackQL `v0.11.660` і новіших версіях. Якщо в `--otel.config` налаштовано експортер, записи `otel` також надсилаються до цієї кінцевої точки | `table` |
| `--otel.config` | string | Рядок JSON / YAML, що налаштовує формат виводу `otel`; `exporter.endpoint`, `exporter.headers`, `exporter.timeout_ms` і `exporter.batch_size` керують надсиланням записів до кінцевої точки журналів OTLP/HTTP, див. [Надсилання до кінцевої точки OTLP](/getting-started/output-modes#pushing-to-an-otlp-endpoint). Доступно в StackQL `v0.12.732` і новіших версіях | `{}` |
| `--preview` | string | Рядок JSON, що вмикає можливості попередньої версії. `{"unstable": true}` відкриває відношення `stackql_unstable_<provider>.<service>.<resource>`, засновані на документах: `omnisdk` визначає та виконує їх безпосередньо з документів провайдерів, передаючи рядки потоком у міру їх отримання; решта ключів (`batchSize`, `flushInterval`, `endpoint`, `insecureSkipTLSVerify`) налаштовують цей бекенд. Можливості попередньої версії нестабільні: поведінка, синтаксис і вивід можуть змінитися або перестати працювати між випусками без попередження, тому не покладайтеся на них у робочому середовищі. Починаючи з `v1.0`, те саме явне ввімкнення відкриває відношення `stackql_preview.iac.run` і `stackql_preview.iac.destroy`, які застосовують і знищують оголошений набір ресурсів через `omnisdk`, зберігаючи стан у кореневому каталозі застосунку. Див. [Можливості попередньої версії](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--provider` | string | Початковий провайдер за замовчуванням. Наприклад, із `--provider github` ім'я `repos.repos` відповідає `github.repos.repos` без попередньої інструкції `USE`. Не виконує автентифікації для провайдера. | немає |
| `--querycachesize` | integer | Розмір кешу LRU для планів запитів, у кількості записів | `10000` |
| `--registry` | string | Рядок JSON / YAML, що налаштовує розташування реєстру провайдерів і перевірку підписів документів провайдерів | див. [`--registry`](#--registry) |
| `--session` | string | Рядок JSON / YAML з конфігурацією сеансу | `{}` |
| `--sqlBackend` | string | Рядок JSON / YAML з конфігурацією системи бекенду SQL | див. [`--sqlBackend`](#--sqlbackend) |
| `--store.txn` | string | Рядок JSON / YAML з конфігурацією сховища Txn | `{}` |
| `--tls.CABundle` | string | Шлях до пакета CA; якщо не вказано, використовуються системні значення за замовчуванням |  |
| `--tls.allowInsecure` | flag | Дозволити довіру до незахищених сертифікатів (не рекомендовано) |  |
| `--upstream.errors` | string | Політика JSON / YAML для явного допущення статусів відповідей HTTP під час читання з провайдерів. Див. [`--upstream.errors`](#--upstream-errors). | `{}` |
| `--var` | string | Зовнішні змінні у вигляді пар "ключ-значення" для підстановки в запити StackQL через файли даних `jsonnet` |  |
| `-v`, `--verbose` | flag | Докладний вивід | `false` |
| `-h`, `--help` | | Контекстна довідка для stackql | |
| `--version` | | Відображає версію програми StackQL | |

Прапорець `--colorscheme` застарілий і більше не змінює кольори оболонки. Прапорець `--usenonpreferredapis` приймається, але в поточному рушії не впливає на вибір API.

## `--registry`

Прапорець `--registry` налаштовує, звідки зчитуються документи провайдерів і чи перевіряються їхні підписи. Значення - це рядок JSON з такими ключами:

| Ключ | Опис | За замовчуванням |
| -- | -- | -- |
| `url` | URL реєстру. Якщо не вказано, використовується публічний реєстр провайдерів StackQL. | публічний реєстр |
| `localDocRoot` | Локальний каталог із документами провайдерів, які зчитуються замість завантаження з реєстру. Використовується під час [розробки провайдера](/developers/developing-stackql-providers#testing-a-provider-locally). | |
| `srcPrefix` | Префікс шляху в корені реєстру, за яким розташовані вихідні документи провайдерів. | `src` |
| `verifyConfig.nopVerify` | Значення `true` вимикає перевірку підписів. Встановіть `false`, щоб вимагати вбудований підпис ML-DSA-65 (FIPS 204) для кожного зчитаного документа провайдера та сервісу, зокрема для відношень попередньої версії, заснованих на документах. | `true` |
| `verifyConfig.publicKeys` | Об'єкт JSON, що зіставляє ідентифікатори ключів із відкритими ключами ML-DSA-65 у шістнадцятковому кодуванні, для приватних реєстрів. Він замінює вбудовані робочі ключі; явно вказаний порожній об'єкт є помилкою. | вбудовані ключі |

### Приклад: вимога підписаних документів провайдерів

Вмикає перевірку для кожного документа провайдера та сервісу, зчитаного з публічного реєстру, за вбудованими робочими ключами:

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

### Приклад: зчитування непідписаних документів із локального каталогу

Спрямовує реєстр на каталог документів провайдерів, що перебувають у розробці. Ці документи не підписані, тому перевірка залишається вимкненою:

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

:::note

Перевірка підписів доступна в StackQL `v1.0` і новіших версіях і за замовчуванням вимкнена. Підписи охоплюють точні байти YAML документа, тому будь-яке редагування, зокрема зміна форматування або символів нового рядка, робить їх недійсними; підпишіть документ повторно за допомогою інструмента реєстру `pqsig sign-doc`. Для непідписаних локальних документів у розробці потрібно залишати `nopVerify: true`. Колишні параметри сертифікатів і файли sidecar `.sig` більше не використовуються, а архіви, опубліковані лише з файлами sidecar, потрібно опублікувати повторно, перш ніж використовувати їх із перевіркою. Перевірка автентифікує документи під час їх зчитування; завантаження та розпакування архівів не охоплюються.

:::

## `--sqlBackend`

Прапорець `--sqlBackend` налаштовує зовнішній бекенд SQL для StackQL, що дає змогу використовувати зовнішній рушій бази даних (наприклад, PostgreSQL) замість вбудованого рушія SQL за замовчуванням. Це корисно, якщо потрібно використовувати зовнішню базу даних для обробки запитів, постійного зберігання або інтеграції з наявною інфраструктурою баз даних.

Значення - це рядок JSON з такими ключами:

| Ключ | Опис | Приклади значень |
| -- | -- | -- |
| `dbEngine` | Тип рушія бази даних | `postgres_tcp` |
| `sqlDialect` | Діалект SQL, який слід використовувати | `postgres` |
| `dsn` | Ім'я джерела даних (рядок підключення) для бази даних | Див. приклади нижче |

### Приклад: використання бекенду PostgreSQL

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

### Приклад: використання інтерфейсу PostgreSQL у Databricks

Databricks надає сумісний із PostgreSQL інтерфейс, який можна використовувати як бекенд SQL для StackQL. DSN використовує стандартний формат рядка підключення PostgreSQL з вашими обліковими даними Databricks:

```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
Спеціальні символи в імені користувача або паролі (наприклад, `@`) мають бути закодовані для URL у DSN (наприклад, `@` стає `%40`).
:::

## `--upstream.errors`

За допомогою `http.ignoreStatusCodes` перелічіть статуси відповідей HTTP, які читання з провайдера має явно допускати. Записи є рядковими значеннями: використовуйте точний код, як-от `"503"`, або клас, як-от `"5xx"`. Значення за замовчуванням `{}` не додає жодних винятків до звичайної обробки відповідей upstream у рушії. Це налаштування не виконує повторних спроб для невдалих запитів і не застосовується до змінення даних або обміну даними автентифікації.

Проігнорована відповідь не додає рядків. Інші операції читання в запиті все одно можуть повертати рядки, тому успішний запит може повернути неповні результати. StackQL повідомляє про проігнорований статус HTTP як діагностичне повідомлення.

Наприклад, цей параметр використовує [тест з'єднання з імітованим GitHub](https://github.com/stackql/stackql/blob/256187fab2410b7c999e7208bd888b12c5df9b9e/test/robot/functional/stackql_mocked_from_cmd_line.robot#L2104):

```bash
stackql exec --upstream.errors='{"http":{"ignoreStatusCodes":["5xx"]}}' \
  "SELECT r.name, c.login FROM github.repos.repos r
   JOIN github.repos.collaborators c ON c.repo = r.name
   WHERE r.org = 'example-org' AND c.owner = 'example-org'
   ORDER BY r.name;"
```

У тесті запит до API на отримання співавторів одного репозиторію повертає HTTP `500`. Запит однаково повертає рядки співавторів для інших репозиторіїв, а stderr містить `ignoring upstream response: 500 INTERNAL SERVER ERROR`. Якщо очікується лише одна помилка, віддавайте перевагу точному коду статусу.
