# Opciones globales

> Opciones globales del binario stackql: autenticación, formato de salida, ubicación del registro, logs y configuración del backend SQL, disponibles en todos los comandos.

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

Las opciones globales especifican el comportamiento del programa en tiempo de ejecución para la aplicación StackQL; estas opciones se establecen en la línea de comandos al iniciar la aplicación StackQL (ya sea en el modo interactivo/shell o en el modo exec no interactivo) o se cargan desde el archivo de inicialización de StackQL ([`.stackqlrc`](/getting-started/using-stackql#the-stackqlrc-initialization-file)).  Las opciones incluyen:  

| Opción | Tipo de datos | Descripción | Valor predeterminado |
| -- | -- | -- | -- |
| `--access.config` | string | Configuración de acceso de los llamadores, un sobre JSON `{"path": "/path/to/access.json"}` (también se acepta solo la ruta del archivo).  Habilita la [gestión de accesos](/command-line-usage/access-management): los llamadores se autentican mediante JWT, token bearer estático, TLS mutuo o identidad local del SO, y las instrucciones se autorizan según reglas de política.  Las credenciales de token locales se leen de `STACKQL_CALLER_TOKEN`.  Disponible a partir de StackQL `v1.0`. | |
| `--acid` | string | Cadena JSON / YAML que representa la configuración ACID | `{}` |
| `--allow-persistent-secrets` | flag | Permite que una sesión seleccione un almacén de secretos persistente del sistema operativo (macOS Keychain, Linux Secret Service o Windows Credential Manager) con `SET "$.secret_store"`.  Los almacenes de archivo plano se rechazan incluso con la opción.  Consulte [Sesiones de provider y secretos](/getting-started/provider-sessions#persistent-os-secret-stores).  Disponible a partir de StackQL `v1.0`. | `false` |
| `--allow-secret-dereference` | flag | Permite desreferenciar los valores de secretos y credenciales en expresiones SQL (`"$secrets.name"`, `"$auth.provider.field"`), con la consecuencia de que pueden acabar en los resultados, los logs y los artefactos de consulta persistidos.  No es necesaria para la autenticación normal de los providers.  Consulte [Valores de secretos en SQL](/getting-started/provider-sessions#secret-values-in-sql).  Disponible a partir de StackQL `v1.0`. | `false` |
| `--apirequesttimeout` | integer | Tiempo de espera de las solicitudes a la API en segundos, 0 para no aplicar tiempo de espera | `45` |
| `--approot` | string | Ruta raíz de la configuración y la caché de la aplicación | `{cwd}/.stackql` |
| `--approotfilemode` | uint32 | Modo de archivo de la configuración y la caché de la aplicación | `493` |
| `--auth` | string | Pares clave-valor del contexto `auth` en formato json |  |
| `--cachekeycount` | integer | Número inicial de claves de la caché | `100` |
| `--configfile` | string | Ruta completa del archivo de configuración | `{cwd}/.stackqlrc` |
| `--cpuprofile` | string | Archivo `cpuprofile`, ninguno si está vacío | `null` |
| `--dataflow.dependency.max` | int | Profundidad máxima de dependencias del flujo de datos para una consulta determinada | `50` |
| `--dataflow.components.max` | int | Número máximo de componentes débilmente conexos del flujo de datos para una consulta determinada | `50` |
| `--dbInternal` | string | Cadena JSON / YAML para configurar el tratamiento de las consultas de mantenimiento interno del SGBD | `{}` |
| `-d`, `--delimiter` | string | Delimitador para la salida csv. Un solo carácter.  Se ignora para toda salida que no sea csv | `,` |
| `--dryrun` | flag | Opción `dryrun`; solo se ejecuta el preprocesador y se devuelve la salida generada a partir de la plantilla | `false` |
| `--env.file` | string | Archivo opcional de estilo dotenv que se carga en el entorno del proceso al iniciar (todos los comandos); la herramienta MCP [`reload_credentials`](/mcp/reload_credentials) lo vuelve a cargar bajo demanda. Se tolera que el archivo no exista; las claves con valores vacíos se omiten; las variables existentes se sobrescriben. No se carga desde `.stackqlrc`. Disponible en las versiones de StackQL posteriores a `v0.10.542`. | `null` |
| `--execution.concurrency.limit` | int | Límite de concurrencia para la ejecución de consultas | `1` |
| `--export.alias` | string | Prefijo de alias de exportación (espacio de nombres o esquema) | |
| `--gc` | string | Cadena JSON / YAML que representa la configuración de GC | `{}` |
| `-H`, `--hideheaders` | flag | Deshabilita los encabezados de columna, válido solo con `--output csv` o `--output text` | `false` |
| `--http.log.enabled` | flag | Muestra la información de las solicitudes http en el terminal | `false` |
| `--http.proxy.host` | string | Host del proxy (déjelo en blanco para no usar proxy) | `null` |
| `--http.proxy.password` | string | Contraseña del proxy | `null` |
| `--http.proxy.port` | integer | Puerto del proxy; cualquier número menor o igual que 0 da como resultado el puerto predeterminado del esquema correspondiente (p. ej., `http -> 80`) | `-1` |
| `--http.proxy.scheme` | string | Esquema del proxy, `http` o `https` | `http` |
| `--http.proxy.user` | string | Usuario del proxy | `null` |
| `--http.response.maxResults` | integer | Número máximo de resultados por solicitud http; cualquier número menor o igual que 0 implica que no hay límite | `-1` |
| `--http.response.pageLimit` | integer | Número máximo de páginas de resultados que se devuelven por recurso; cualquier número menor o igual que 0 implica que no hay límite | `20` |
| `--indirect.depth.max` | integer | Profundidad máxima de las consultas indirectas: vistas y subconsultas | `5` |
| `-i`, `--infile` | string | Archivo de entrada (archivo IQL) del que se leen las consultas | `{stdin}` |
| `-q`, `--iqldata` | string | Archivo de contexto (datos) para el uso de plantillas (archivo `json` o `jsonnet`)| |
| `--loglevel` | string | Nivel de log, debe ser uno de  | `fatal` |
| `--mcp.config` | string | Objeto de configuración JSON / YAML para el [servidor MCP](/command-line-usage/mcp#mcp-configuration-object) (`stackql mcp` y `stackql srv`) | `{}` |
| `--mcp.log.format` | string | Codificación del log de auditoría de MCP, `jsonl` u `otel` (registros de log OTLP/JSON); tiene prioridad sobre `server.audit.format` en `--mcp.config`.  Consulte [Formato del log](/command-line-usage/mcp#log-format).  Disponible a partir de StackQL `v0.11.660`. | `jsonl` |
| `--mcp.protocol.version` | string | Revisión más reciente del protocolo MCP que se anuncia, `auto`, `2026-07-28` (solo sin sesión) o una revisión anterior como `2025-11-25`; tiene prioridad sobre `server.protocol_version` en `--mcp.config`.  Consulte [Fijar la revisión](/command-line-usage/mcp#pinning-the-revision).  Disponible a partir de StackQL `v0.12.732`. | `auto` |
| `--mcp.server.type` | string | Tipo de servidor MCP, uno de .  Consulte [Tipo de servidor MCP](/command-line-usage/mcp#mcp-server-type). | `http` |
| `--metadatattl` | integer | TTL de los documentos de metadatos en caché, en segundos | `3600` |
| `--namespaces` | string | Cadena JSON / YAML que representa los espacios de nombres para la caché, las vistas, etc. | `{}` |
| `--offline` | flag | Trabaja sin conexión, con datos en caché | `false` |
| `-f`, `--outfile` | string | Archivo de salida en el que se escriben los resultados | `{stdout}` |
| `-o`, `--output` | string | Formato de salida, debe ser uno de  (`ndjson` se acepta como alias de `jsonl`).  `otel` emite registros de log de OpenTelemetry, consulte [Modos de salida](/getting-started/output-modes#otel-output); disponible a partir de StackQL `v0.11.660`.  Con un exportador configurado en `--otel.config`, los registros `otel` también se envían a ese endpoint | `table` |
| `--otel.config` | string | Cadena JSON / YAML que configura el formato de salida `otel`; `exporter.endpoint`, `exporter.headers`, `exporter.timeout_ms` y `exporter.batch_size` envían los registros a un endpoint de logs OTLP/HTTP, consulte [Enviar a un endpoint OTLP](/getting-started/output-modes#pushing-to-an-otlp-endpoint).  Disponible a partir de StackQL `v0.12.732` | `{}` |
| `--preview` | string | Cadena JSON que habilita la funcionalidad en versión preliminar.  `{"unstable": true}` expone las relaciones `stackql_unstable_<provider>.<service>.<resource>` basadas en documentos, que `omnisdk` resuelve y ejecuta directamente a partir de los documentos de provider, con las filas transmitidas a medida que se producen; las claves restantes (`batchSize`, `flushInterval`, `endpoint`, `insecureSkipTLSVerify`) ajustan ese backend.  La funcionalidad en versión preliminar no es estable: el comportamiento, la sintaxis y la salida pueden cambiar o dejar de funcionar entre versiones sin previo aviso, así que no dependa de ella en producción.  A partir de `v1.0`, la misma activación explícita expone las relaciones `stackql_preview.iac.run` y `stackql_preview.iac.destroy`, que aplican y eliminan un conjunto de recursos declarado mediante `omnisdk`, con el estado guardado en la raíz de la aplicación.  Consulte [Funcionalidad en versión preliminar](https://github.com/stackql/stackql/blob/main/docs/preview.md) | `{}` |
| `--querycachesize` | integer | Tamaño, en número de entradas, de la caché LRU para los planes de consulta | `10000` |
| `--registry` | string | Cadena JSON / YAML que configura la ubicación del registro de providers y la verificación de firmas de los documentos de provider | consulte [`--registry`](#--registry) |
| `--session` | string | Cadena JSON / YAML que representa la configuración de la sesión | `{}` |
| `--sqlBackend` | string | Cadena JSON / YAML que representa la configuración del sistema de backend SQL | consulte [`--sqlBackend`](#--sqlbackend) |
| `--store.txn` | string | Cadena JSON / YAML que representa la configuración del almacén de transacciones | `{}` |
| `--tls.CABundle` | string | Ruta del bundle de CA; si no se especifica, se usan los valores predeterminados del sistema |  |
| `--tls.allowInsecure` | flag | Permite confiar en certificados no seguros (no recomendado) |  |
| `--var` | string | Variables externas proporcionadas como pares clave/valor para cargarlas en las consultas de StackQL mediante archivos de datos `jsonnet` |  |
| `-v`, `--verbose` | flag | Salida detallada | `false` |
| `-h`, `--help` | | Ayuda contextual de stackql | |
| `--version` | | Muestra la versión del programa StackQL | |

## `--registry`

La opción `--registry` configura de dónde se leen los documentos de provider y si se verifican sus firmas.  El valor es una cadena JSON con las siguientes claves:

| Clave | Descripción | Valor predeterminado |
| -- | -- | -- |
| `url` | URL del registro.  Si se omite, se usa el registro de providers público de StackQL. | registro público |
| `localDocRoot` | Un directorio local que contiene documentos de provider, que se leen en lugar de descargarlos del registro.  Se usa al [desarrollar un provider](/developers/developing-stackql-providers#testing-a-provider-locally). | |
| `srcPrefix` | Prefijo de ruta bajo la raíz del registro donde se encuentran los documentos de origen de los providers. | `src` |
| `verifyConfig.nopVerify` | `true` omite la verificación de firmas.  Establézcalo en `false` para exigir una firma ML-DSA-65 (FIPS 204) integrada en cada documento de provider y de servicio que se lea, incluidas las relaciones en versión preliminar basadas en documentos. | `true` |
| `verifyConfig.publicKeys` | Un objeto JSON que asigna ID de clave a claves públicas ML-DSA-65 codificadas en hexadecimal, para registros privados.  Sustituye a las claves de producción integradas; un objeto vacío explícito es un error. | claves integradas |

### Ejemplo: exigir documentos de provider firmados

Activa la verificación para cada documento de provider y de servicio que se lee del registro público, que se comprueba con las claves de producción integradas:

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

### Ejemplo: leer documentos sin firmar desde un directorio local

Apunta el registro a un directorio de documentos de provider en desarrollo.  Esos documentos no están firmados, por lo que la verificación permanece desactivada:

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

:::note

La verificación de firmas está disponible a partir de StackQL `v1.0` y está desactivada de forma predeterminada.  Las firmas cubren los bytes YAML exactos de un documento, por lo que cualquier modificación, incluido un cambio de formato o de salto de línea, las invalida; vuelva a firmar con la herramienta `pqsig sign-doc` del registro.  Los documentos locales de desarrollo sin firmar deben mantener `nopVerify: true`.  Las antiguas opciones de certificado y los archivos sidecar `.sig` ya no se usan, y los archivos comprimidos publicados solo con sidecars deben volver a publicarse antes de usarlos con verificación.  La verificación autentica los documentos cuando se leen; la descarga y la extracción de los archivos comprimidos no están cubiertas.

:::

## `--sqlBackend`

La opción `--sqlBackend` configura un backend SQL externo para StackQL, lo que le permite usar un motor de base de datos externo (como PostgreSQL) en lugar del motor SQL integrado predeterminado. Esto resulta útil para aprovechar una base de datos externa para el procesamiento de consultas, el almacenamiento persistente o la integración con una infraestructura de bases de datos existente.

El valor es una cadena JSON con las siguientes claves:

| Clave | Descripción | Valores de ejemplo |
| -- | -- | -- |
| `dbEngine` | El tipo de motor de base de datos | `postgres_tcp` |
| `sqlDialect` | El dialecto SQL que se va a usar | `postgres` |
| `dsn` | El nombre del origen de datos (cadena de conexión) de la base de datos | Consulte los ejemplos siguientes |

### Ejemplo: usar un backend PostgreSQL

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

### Ejemplo: usar la interfaz PostgreSQL de Databricks

Databricks expone una interfaz compatible con PostgreSQL que se puede usar como backend SQL de StackQL. El DSN usa el formato estándar de cadena de conexión de PostgreSQL con sus credenciales de 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
Los caracteres especiales del nombre de usuario o de la contraseña (como `@`) deben codificarse como URL en el DSN (p. ej., `@` se convierte en `%40`).
:::