# Interfaz de línea de comandos

La interfaz de línea de comandos (CLI) de `keenauth` llama a la API de gestión desde una terminal o un script. Cada comando envuelve un método tipado del SDK de Go, por lo que la CLI y la API se comportan de la misma manera. Todavía no hay un paquete de instalación.

## Autenticación y destino

La CLI lee sus credenciales solo desde el entorno. La clave de API nunca se acepta como indicador, de modo que no queda en el historial de su shell.

| Variable | Obligatorio | Descripción |
|---|---|---|
| `KEENAUTH_API_KEY` | sí | Clave de API de gestión. Si falta, el comando termina con el código 3. |
| `KEENAUTH_BASE_URL` | sí, salvo que se indique `--base-url` | URL base de la API de gestión de su entorno. |

En lugar de una clave de API, puede iniciar sesión con su cuenta del panel: `keenauth login`, y luego `keenauth env use <environment_id>`. La sesión se usa solo cuando `KEENAUTH_API_KEY` no está definida, y la dirección del entorno se obtiene entonces del plano de control (consulte [Iniciar sesión con keenauth login](/docs/cli/login)).

El indicador `--base-url` anula `KEENAUTH_BASE_URL` para un comando. La CLI nunca muestra la clave de API; si una respuesta del servidor la repite, se reemplaza por `[redacted]`.

## Comandos

Los comandos siguen el patrón `keenauth <group> <action> [arguments] [flags]`. Ejecute `keenauth --help` o `keenauth <group> --help` para ver la lista completa.

| Grupo | Acciones |
|---|---|
| `users` | `list`, `search`, `get`, `create`, `update`, `delete`, `block`, `unblock`, `cancel-deletion`, `authenticators list`, `authenticators delete`, `authenticators reset`, `authenticators reactivate`, `send-password-reset`, `send-verification-email`, `emails send-verification`, `start-recovery`, `logs list` |
| `applications` | `list`, `create`, `get`, `update`, `delete`, `get-api-grant`, `put-api-grant`, `delete-api-grant`, `credentials list`, `credentials create`, `credentials delete` |
| `apis` | `list`, `create`, `get`, `update`, `delete` |
| `connections` | `list`, `create`, `get`, `update`, `delete`, `activate`, `deactivate` |
| `identity-settings` | `get`, `update` |
| `environment-settings` | `get`, `update` |
| `config` | `export` (sin `-o` muestra YAML), `plan -f <file>` (muestra un diff legible en una terminal), `plans get`, `apply <plan_id>` (pide confirmación; `--secrets-from-env` lee secretos de variables de entorno, `--confirm-deletion <kind>/<key>`), `promote --from <env> --to <env>` (exporta, planifica, muestra el diff y aplica tras confirmación; consulte [Promover configuración con keenauth config promote](/docs/cli/config-promote)) |
| `api-keys` | `list`, `get`, `create`, `rotate`, `revoke` |
| `logs` | `list`, `get`, `tail` (sigue los registros nuevos; `--type`, `--user`, `--org`; consulte [Seguir registros con keenauth logs tail](/docs/cli/tail)) |
| `support-access-grants` | `list`, `get`, `create`, `delete` (consulte [Conceder acceso de soporte con keenauth support-access-grants](/docs/cli/support-access-grants)) |
| `directories` | `simulate <directory_id> --scenario <name>` (ejecuta un escenario del simulador SCIM en desarrollo y staging; consulte [Probar el aprovisionamiento SCIM con keenauth directories simulate](/docs/cli/directories-simulate)) |
| `audit` | `verify` (verifica una exportación de auditoría descargada sin conexión; consulte [Verificar exportaciones de auditoría con keenauth audit verify](/docs/cli/audit-verify)) |
| `branding` | `get`, `update`, `applications get`, `applications put`, `organizations get`, `organizations put`, `css put`, `page-template put`, `publish`, `rollback`, `versions list`, `texts get`, `texts put`, `texts delete` |
| `signing-keys` | `list`, `rotate`, `policy get`, `policy update` |
| `events` | `tail` (sigue los eventos de clientes mediante la API de eventos; consulte [Seguir eventos con keenauth events tail](/docs/cli/events-tail)), `get <event ID>` (un evento, exactamente como lo envió el servidor) |
| `mock` | `serve` ejecuta un servidor simulado OIDC local para pruebas sin conexión; no necesita clave de API (consulte [Servidor simulado local](/docs/cli/mock-server)) |
| `test` | `login --user <+test address>` inicia sesión a un usuario de prueba en un entorno `development` con el código fijo e imprime los tokens; no necesita clave de API (consulte [Iniciar sesión de usuarios de prueba con keenauth test login](/docs/cli/test-login)) |
| `webhooks` | `listen --forward-to <local URL>` reenvía los eventos de un entorno `development` o `staging` a su equipo, firmados con un secreto temporal (consulte [Probar webhooks localmente con keenauth webhooks listen](/docs/cli/webhooks-listen)) |
| `login`, `logout`, `whoami`, `env` | `login` (`--web`, `--insecure-storage`), `logout`, `whoami`, `env use <environment_id>`, `env list`: inicie sesión con su cuenta del panel en lugar de una clave de API (consulte [Iniciar sesión con keenauth login](/docs/cli/login)) |

Los comandos de listado aceptan `--limit`, `--after`, `--before` y `--order`. Cuando hay más resultados, el siguiente cursor se imprime en stderr como `more results: --after <cursor>`.

## Formato de salida

`--output` (`-o`) selecciona `table`, `json` o `yaml`. Sin el indicador, la CLI imprime una tabla en una terminal y JSON en caso contrario. JSON y YAML contienen la respuesta de la API sin cambios y nunca se traducen, para que los scripts puedan confiar en ellos. Los resultados van a stdout; los errores, las sugerencias y la línea `etag` van a stderr.

## Cuerpos de solicitud

Los comandos que envían un cuerpo aceptan un indicador por cada campo plano, con el nombre de la clave JSON con guiones (`phone_number` se convierte en `--phone-number`). Los objetos anidados se indican con `--data`:

- `--data @file.json` lee el cuerpo desde un archivo.
- `--data -` lee el cuerpo desde la entrada estándar.

Los indicadores sobrescriben los campos del archivo. Un cuerpo está limitado a 4 MiB.

```sh
keenauth users create --email ada@example.com
keenauth apis create --data @api.json
echo '{"name":"Orders"}' | keenauth apis update api_123 --data - --if-match '"v3"'
```

## Concurrencia optimista: `--if-match` y el etag

Los comandos de actualización y eliminación de aplicaciones, API y conexiones requieren `--if-match`; `users update` lo acepta. El valor es el `ETag` de la versión que desea modificar. El servidor rechaza la solicitud si el recurso cambió entretanto. `identity-settings update` también lo requiere. `environment-settings update` también lo requiere. Las escrituras del borrador de marca (`branding update`, `branding applications put`, `branding organizations put`, `branding css put`, `branding page-template put`) también lo requieren.

Cada comando `get` (`users`, `applications`, `apis`, `connections`, `identity-settings`, `environment-settings`) imprime la respuesta `ETag` en stderr, para que stdout quede limpio:

```sh
$ keenauth apis get api_123
{ ... }
etag: "v3"
$ keenauth apis update api_123 --name Orders --if-match '"v3"'
```

La línea `etag` no se añade a la salida JSON ni YAML.

## Comandos destructivos y `--yes`

Los comandos que eliminan o bloquean piden confirmación (`[y/N]`) en una terminal. Si la rechaza, el comando termina con el código 1 e imprime `aborted`. Cuando la entrada estándar no es una terminal, el comando se niega a ejecutarse a menos que pase `--yes` (`-y`); termina con el código 2 antes de enviar cualquier solicitud.

## Códigos de salida

| Código | Significado |
|---|---|
| `0` | Éxito. |
| `1` | Error del servidor u operativo, una confirmación rechazada o un fallo de red. |
| `2` | Error de uso: comando o indicador desconocido, un argumento que falta, un cuerpo no válido o `--yes` ausente en una terminal no interactiva. |
| `3` | Error de autenticación: falta la clave, o el servidor respondió 401 o 403. |
| `4` | El plan no incluye la función (`403` con `plan_feature_unavailable`). |

Para los errores del servidor, la CLI imprime `error`, `code`, `status`, `detail`, `request_id` y una línea `field` por cada error de validación en stderr. Cite el `request_id` cuando contacte con soporte.

## Idioma

El texto legible por personas (ayuda, avisos, errores, encabezados de tabla) está disponible en turco (`tr`), inglés (`en`), francés (`fr`), alemán (`de`), coreano (`ko`), japonés (`ja`), italiano (`it`) y español (`es`). El idioma se toma del primer conjunto de estas variables: `KEENAUTH_LANG`, `LC_ALL`, `LC_MESSAGES`, `LANG` (por ejemplo, `tr_TR.UTF-8` selecciona `tr`). Un valor vacío o no compatible selecciona inglés, y un mensaje que falte en un idioma recurre al inglés.

La salida legible por máquinas nunca se traduce: los nombres y valores de los campos JSON y YAML, el `code` del problema y las etiquetas `code`, `status` y `request_id` permanecen iguales en todos los idiomas. Los mensajes que provienen del servidor se muestran tal como los envió el servidor.

```sh
KEENAUTH_LANG=de keenauth users list --help
```

## Credenciales de aplicación

`keenauth applications credentials list|create|delete` gestiona los secretos de cliente y las claves públicas registradas de una aplicación. Estos comandos no usan `--if-match`.

```sh
keenauth applications credentials create app_123 --type client-secret --expires-at 2027-01-01T00:00:00Z
keenauth applications credentials create app_123 --type public-key --jwk-file key.pub.jwk
keenauth applications credentials delete app_123 cred_456 --yes
```

Un secreto de cliente se imprime una sola vez, en stdout, junto con una advertencia única en stderr. `--jwk-file` acepta una única JWK pública (como máximo 16 KiB); un archivo con miembros privados se rechaza antes de enviar cualquier solicitud.

## Claves de API

`keenauth api-keys list|get|create|rotate|revoke` gestiona las claves de API de gestión del entorno. Estos comandos no usan `--if-match`.

```sh
keenauth api-keys create --name ci --type restricted --permissions users:read,users:write --expires-at 2027-10-01T00:00:00Z
keenauth api-keys rotate key_123 --overlap-hours 24
keenauth api-keys revoke key_123 --reason leaked --yes
```

La clave sin procesar de `create` y `rotate` se imprime una sola vez, en stdout, junto con una advertencia única en stderr; no puede volver a recuperarse. `list` y `get` imprimen solo metadatos.