# Guardar un secreto

> Crea o actualiza un secreto disponible en los workers como plz.env.KEY.

Fuente: https://developers.plazbot.com/cli/workers/secret-set/

### Guardar un secreto

Crea o actualiza un secreto encriptado del workspace. Todos los workers lo leen como `plz.env.<KEY>`. Si la clave ya existe, su valor se reemplaza. Los valores nunca se vuelven a mostrar.

```bash
plazbot workers secret set <key> [value] [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Clave | `<key>` | Sí | Nombre en `UPPER_SNAKE_CASE`: letras mayúsculas, dígitos y guiones bajos, empezando por letra (`^[A-Z][A-Z0-9_]*$`). Ej: `STRIPE_API_KEY`. |
| Valor | `[value]` | No | Valor del secreto. Si lo omites, el CLI lo pide con entrada oculta o lo lee de stdin. |
| JSON | `--json` | No | Imprime `{"key","saved"}` como JSON. Nunca incluye el valor. |

### Ejemplos

```bash
# Pedir el valor con entrada oculta
plazbot workers secret set STRIPE_API_KEY

# Leer el valor de stdin (recomendado en scripts y CI)
echo "$STRIPE_KEY" | plazbot workers secret set STRIPE_API_KEY

# Leer el valor de un archivo
plazbot workers secret set GOOGLE_CREDENTIALS < ./service-account.json

# Pasar el valor en línea (queda en el historial de la shell)
plazbot workers secret set API_BASE_URL https://api.example.com
```

> **Importante:** Pasar el valor como argumento lo deja en el historial de tu shell y en la lista de procesos. Prefiere el prompt oculto o stdin: `echo "$STRIPE_KEY" | plazbot workers secret set STRIPE_API_KEY`. Al leer de stdin se quita el salto de línea final que agrega `echo`.

### Resultado

```text
✔ Value for STRIPE_API_KEY: ********************
✔ Secret "STRIPE_API_KEY" saved
Available in your workers as plz.env.STRIPE_API_KEY
```

Si pasaste el valor como argumento, se añade el aviso `Tip: omit the value (or pipe it through stdin) to keep it out of your shell history.`

### Salida JSON

```json
{ "key": "STRIPE_API_KEY", "saved": true }
```

Con `--json` el valor debe llegar como argumento o por stdin; no se muestra el prompt.

### Uso desde un worker

```typescript
async handler(input, plz) {
const res = await plz.fetch('https://api.stripe.com/v1/customers', {
  headers: { Authorization: `Bearer ${plz.env.STRIPE_API_KEY}` },
})
// ...
}
```

Cada workspace tiene sus propios secretos. Para ver cuáles existen usa [`plazbot workers secret list`](https://developers.plazbot.com/cli/workers/secret-list).

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `Invalid secret name "<key>". Use UPPER_SNAKE_CASE: ...` | La clave no cumple el formato. | Usa mayúsculas, dígitos y `_`, empezando por letra: `STRIPE_API_KEY`. |
| `No secret value received on stdin.` | Sin terminal y sin valor por stdin. | `echo "$VALUE" \| plazbot workers secret set <KEY>`. |
| `The secret value is required in --json mode.` | Usaste `--json` sin valor ni stdin. | Pasa el valor por stdin. |
| `The secret value cannot be empty.` | El valor está vacío o solo tiene espacios. | Envía un valor no vacío. |
| `You are not signed in.` | No hay sesión. | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login). |