// Engineering Log
Secretos y zero trust: Parte 3 — Bitwarden CLI en Linux: bw, sesión y uso seguro
Publicado el 20.11.2026 · Autor: Mikhail Gorbachev
// Ruta rápida
Este artículo pertenece al tema Servidores e infraestructura.
Bitwarden CLI (bw) — el cliente oficial de Bitwarden para la línea de comandos. Con él se puede buscar, leer, crear, modificar y eliminar entradas, y trabajar con organizaciones y colecciones. Permite insertar secretos del almacén en scripts y comandos de administración en lugar de mantenerlos en .env, en el historial del shell o en notas. bw funciona tanto con la nube de Bitwarden como con el servidor propio Vaultwarden. A continuación se explica cómo instalar bw en Linux, conectarlo a Vaultwarden y usarlo de manera que los secretos no queden en disco, en los registros ni en la lista de procesos. La información está verificada según la documentación de Bitwarden y el código fuente del CLI versión 2026.10.0.
Instalación
Hay tres maneras.
npm. Se necesita Node.js 22 o superior y npm 10 o superior:
node --version # v22.x o superior
npm install -g @bitwarden/cli
bw --versionLa documentación advierte: en Linux, para instalar vía npm puede hacer falta build-essential (sudo apt install build-essential) o su equivalente en su distribución. En arm64 (por ejemplo, en Raspberry Pi) la documentación recomienda usar npm: los binarios precompilados se publican solo para x64.
snap:
sudo snap install bwBinario nativo para Linux x64 que funciona sin Node.js:
curl -fsSL -o bw.zip 'https://bitwarden.com/download/?app=cli&platform=linux'
unzip bw.zip && chmod +x bw && sudo mv bw /usr/local/bin/Para las compilaciones publicadas en GitHub se incluyen archivos con sumas de verificación SHA-256; antes de instalar, verifique la suma del archivo: tome el archivo con la suma en la página de la release en GitHub (compruebe allí el nombre exacto del archivo) y verifíquelo con sha256sum -c. Allí también hay dos variantes: la normal y OSS. En la compilación OSS no hay funciones con licencia cerrada, por ejemplo comandos de aprobación de dispositivos; para trabajar con Vaultwarden basta cualquiera de las dos.
Conexión a Vaultwarden
Por defecto bw se conecta a la nube de Bitwarden. Para usar su propio servidor, especifique la dirección antes de iniciar sesión:
bw config server https://vault.example.ru
bw config server # sin argumento muestra la dirección actualSi el servidor entrega un certificado autofirmado o uno de su CA interna, indique el fichero PEM del certificado raíz de Node.js:
export NODE_EXTRA_CA_CERTS="$HOME/.config/bw/example-ca.pem"No es necesario desactivar la verificación de certificados: el CLI envía al servidor un hash de la contraseña maestra y recibe tokens de acceso. Cómo desplegar el servidor detrás de un proxy inverso está descrito en la parte sobre Vaultwarden.
Inicio de sesión y desbloqueo — pasos distintos
El CLI tiene tres estados, que muestra bw status:
bw status | jq -r .status
# unauthenticated — no autenticado
# locked — autenticado, almacén bloqueado
# unlocked — almacén desbloqueadoInicio de sesión (bw login) vincula el CLI con la cuenta: el servidor le verifica, emite tokens y el CLI descarga el almacén cifrado. Desbloqueo (bw unlock) descifra el almacén en su máquina con la contraseña maestra y crea una clave de sesión. El inicio de sesión se hace una vez, el desbloqueo se realiza cada vez que se trabaja.
bw login you@example.ru # preguntará la contraseña maestra y, si está activado, el segundo factor
bw unlock # preguntará la contraseña maestra y devolverá la clave de sesiónEl inicio por e-mail y contraseña crea también la clave de sesión. Si se inicia sesión con una API key o mediante SSO, luego es obligatorio bw unlock: los datos solo se pueden descifrar con la contraseña maestra. Los comandos config, encode, generate, update y status funcionan sin desbloquear.
Inicio de sesión en dos pasos en el CLI
El CLI soporta tres métodos de segundo factor: app de autenticación (TOTP), código por e-mail y YubiKey OTP. El número del método se pasa en --method:
| Método | --method |
|---|---|
| Authenticator (TOTP) | 0 |
| 1 | |
| YubiKey OTP | 3 |
bw login you@example.ru --method 0 --code 123456FIDO2 WebAuthn y Duo no están soportados por el CLI. Si en la cuenta solo están habilitados esos métodos, solo podrá iniciar sesión con una API key (ver más abajo). La contraseña debe introducirse de forma interactiva para que no quede en el historial del shell; el código de un solo uso pasado como argumento del comando será visible en la lista de procesos mientras el comando esté en ejecución.
Clave de sesión: BW_SESSION y –raw
bw unlock imprime el comando listo export BW_SESSION="…". Con la opción global --raw muestra solo la clave, sin explicaciones, por lo que es cómodo asignarla directamente a una variable:
export BW_SESSION="$(bw unlock --raw)"La solicitud de contraseña del CLI se envía a stderr, por lo que al capturar stdout el prompt «Master password:» queda en pantalla y en la variable solo queda la clave. En lugar de una variable de entorno, puede pasar la clave con la opción --session <clave>, pero entonces será visible en la lista de procesos.
La clave de sesión vale hasta bw lock o bw logout y no se propaga por sí sola a nuevas ventanas de terminal. Al terminar, bloquee el almacén:
bw lock
unset BW_SESSIONbw lock bloquea el almacén y borra el estado guardado; después de bw lock la clave de sesión deja de abrir los datos.
La contraseña no en argumentos de la línea de comandos
bw unlock acepta la contraseña como argumento posicional: bw unlock <contraseña>. No debe hacerse así:
- los argumentos de cualquier proceso son visibles para todos los usuarios del sistema en
ps auxy en/proc/<pid>/cmdlinemientras el proceso está activo (si/procno está montado conhidepid); - el comando con la contraseña entra en el historial del shell (
~/.bash_history,~/.zsh_history); - también puede ir al registro de auditoría si en el servidor está activado
auditdcon registro deexecve.
Para el desbloqueo no interactivo hay dos opciones seguras.
--passwordenv <nombre> — el CLI lee la contraseña de la variable de entorno con el nombre indicado. El nombre puede ser cualquiera; BW_PASSWORD en la documentación es solo un ejemplo. Las variables de entorno de un proceso solo pueden leerse por el propietario del proceso y por root a través de /proc/<pid>/environ, no por todos los usuarios:
# bash; en zsh: read -rs '?Contraseña maestra: ' BW_PW
read -rs -p 'Contraseña maestra: ' BW_PW; echo
BW_SESSION="$(BW_PW="$BW_PW" bw unlock --passwordenv BW_PW --raw)"
export BW_SESSION
unset BW_PWLa forma BW_PW="$BW_PW" bw … pasa la variable solo a ese proceso sin exportarla en el shell.
--passwordfile <archivo> — el CLI toma la contraseña de la primera línea del archivo. La documentación aconseja restringir el acceso a ese archivo; el CLI no comprueba permisos. Cree el archivo ya con los permisos correctos, no los cambie después:
mkdir -p -m 700 ~/.config/bw
( umask 077; read -rs -p 'Contraseña maestra: ' P; printf '%s\n' "$P" > ~/.config/bw/master ); unset P; echo
bw unlock --passwordfile ~/.config/bw/master --rawLa contraseña maestra en un archivo en disco es la contraseña maestra en texto claro: cualquiera que consiga una copia del disco o una copia de seguridad del home podrá leerla. Use este método solo en servidores donde no pueda prescindir del desbloqueo automático y considérelo en su modelo de amenazas. Cómo eliminar la contraseña del disco y desbloquear el almacén con la pulsación de una clave hardware está descrito en la parte sobre desbloqueo por FIDO2.
Dónde guardar la clave de sesión
La clave de sesión junto con la copia local del almacén da acceso a todas las entradas, así que trátela como una contraseña. Para no tener que desbloquear en cada terminal nuevo, puede guardar la clave en $XDG_RUNTIME_DIR. En sistemas con systemd ese directorio es /run/user/<uid> en tmpfs con permisos 0700: está en memoria, solo usted tiene acceso y se limpia al cerrar todas las sesiones (si no está activado loginctl enable-linger para el usuario) o al reiniciar.
# desbloquear y guardar la clave
umask 077
( umask 077; bw unlock --raw > "$XDG_RUNTIME_DIR/bw-session" ) # si la desbloqueo falla, elimine el archivo vacío
# en ~/.bashrc: recoger la clave en nuevas shells
[ -r "$XDG_RUNTIME_DIR/bw-session" ] && export BW_SESSION="$(cat "$XDG_RUNTIME_DIR/bw-session")"
# finalizar
bw lock; rm -f "$XDG_RUNTIME_DIR/bw-session"; unset BW_SESSIONQué no hacer:
- escribir la clave de sesión en
~/.bashrc,~/.profile,.envo cualquier otro archivo en disco; - volcarla en el registro de un script:
set -xen bash imprime los comandos con los valores de los argumentos (por ejemplo,export VAR=valor), por eso alrededor de operaciones con secretos se desactiva el trace (set +x); - pegarla en chats, tickets o tareas de CI;
- mantener el almacén desbloqueado en un servidor compartido donde otras personas o servicios operen con su cuenta.
Recuerde que cualquier proceso lanzado con su usuario puede leer tanto $XDG_RUNTIME_DIR como las variables de entorno de sus procesos. El tmpfs protege contra el robo del disco y contra otros usuarios, pero no contra un programa malicioso en su misma sesión.
Lectura de secretos
bw get devuelve un objeto por ID o por cadena de búsqueda:
bw get password db.example.ru # solo la contraseña
bw get username db.example.ru
bw get totp db.example.ru # código TOTP actual
bw get notes deploy-key
bw get item db.example.ru | jq . # entrada completa en JSONSi la cadena coincide con varias entradas, el CLI da el error «More than one result was found» e imprime sus IDs. Encuentre la correcta con bw list y luego refiérase por ID:
bw list items --search db | jq -r '.[] | [.id, .name, .login.username] | @tsv'
bw get password 0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0cLos filtros --folderid, --collectionid, --organizationid, --url se combinan entre sí con OR, y con --search con AND. Un campo de los campos personalizados de una entrada se obtiene con jq:
bw get item 0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c \
| jq -r '.fields[]? | select(.name == "api_token") | .value'No hace falta mostrar el secreto en pantalla para usarlo. Páselo directamente al comando mediante una variable de entorno o stdin:
# variable de entorno solo para un proceso
PGPASSWORD="$(bw get password db.example.ru)" psql -h db.example.ru -U app appdb
# entrada estándar
bw get password registry.example.ru | docker login registry.example.ru -u deploy --password-stdinSi ha cambiado una entrada en otro cliente, ejecute bw sync: este comando solo descarga el almacén desde el servidor. Los cambios hechos con el CLI (create, edit, delete) se envían al servidor inmediatamente. El tiempo de la última sincronización lo muestra bw sync --last.
Crear, editar y eliminar entradas
bw create y bw edit aceptan JSON en base64. El flujo es: tomar una plantilla, rellenarla con jq, codificar con bw encode, y pasar a bw create. No incluya la contraseña en el texto del filtro jq: entonces aparecerá en los argumentos del proceso y en el historial. Es más seguro generar la contraseña en una variable y pasarla a jq vía entorno (env.PW):
PW="$(bw generate -ulns --length 32)"
bw get template item | PW="$PW" jq '
.type = 1
| .name = "db.example.ru"
| .notes = null
| .login = {
username: "app",
password: env.PW,
uris: [{match: null, uri: "https://db.example.ru"}]
}' \
| bw encode | bw create item | jq -r .id
unset PWTipos de entradas: 1 — login, 2 — nota segura, 3 — tarjeta, 4 — datos personales, 5 — clave SSH.
La edición reemplaza la entrada entera, por eso se obtiene la versión actual, se modifica el campo necesario y se envía de nuevo:
ID=0f4c9a2e-1b7d-4c8e-9a3f-5d6e7f8a9b0c
NEW="$(bw generate -ulns --length 32)"
bw get item "$ID" | NEW="$NEW" jq '.login.password = env.NEW' | bw encode | bw edit item "$ID"
unset NEWLa eliminación por defecto mueve la entrada a la papelera, desde donde se puede restaurar. En la nube de Bitwarden la entrada permanece en la papelera 30 días; en Vaultwarden el periodo lo define TRASH_AUTO_DELETE_DAYS (por defecto las entradas no se eliminan automáticamente). Con --permanent la entrada se borra de forma irreversible:
bw delete item "$ID"
bw list items --trash | jq -r '.[] | [.id, .name] | @tsv'
bw restore item "$ID"Entrada de clave SSH
Para entradas de tipo 5 no hay una plantilla lista en la lista de documentación (item.sshKey no aparece entre las plantillas). Se construye el JSON a partir de la plantilla item y del objeto sshKey con tres campos: privateKey, publicKey y keyFingerprint. En el código fuente del cliente los tres están marcados como obligatorios:
KEY=~/.ssh/id_ed25519
bw get template item | jq \
--rawfile priv "$KEY" \
--rawfile pub "$KEY.pub" \
--arg fp "$(ssh-keygen -lf "$KEY.pub" | awk '{print $2}')" '
.type = 5
| .name = "ssh: deploy@example.ru"
| .login = null
| .notes = null
| .sshKey = {privateKey: $priv, publicKey: ($pub | rtrimstr("\n")), keyFingerprint: $fp}' \
| bw encode | bw create item | jq -r .idLa clave privada la lee jq desde un archivo (--rawfile) y no desde un argumento; la huella es pública y se puede pasar con --arg. El soporte de este tipo depende de la versión del servidor, así que primero cree una entrada de prueba y ábrala en la interfaz web de Vaultwarden. El agente SSH integrado que entrega esas claves al programa ssh existe en la app de escritorio de Bitwarden.
Inicio de sesión con API key
La API key personal (client_id y client_secret) se obtiene en la interfaz web en la configuración de seguridad de la cuenta. Es necesaria si en la cuenta está activado un segundo factor que el CLI no soporta, y para automatizaciones donde no se puede responder a la petición del código:
export BW_CLIENTID='<client_id>'
export BW_CLIENTSECRET='<client_secret>'
bw login --apikey
# Configure BW_PW de la misma forma que en la sección sobre --passwordenv
bw unlock --passwordenv BW_PW --rawEl inicio con API key está pensado para casos donde no se puede introducir el código del segundo factor, así que no guarde client_secret y la contraseña maestra juntos salvo que haga falta. La documentación lo dice claramente: la API key no sustituye la contraseña maestra. Solo permite iniciar sesión; para leer los datos hace falta bw unlock con la contraseña maestra. La fuga de la API key sin la contraseña maestra no revela el contenido del almacén, pero permite iniciar sesión en su nombre y descargar los datos cifrados; por tanto guarde la API key con el mismo cuidado que una contraseña y reemítala si sospecha una fuga.
Organizaciones, colecciones y permisos
Los secretos compartidos del equipo se guardan en una organización y se reparten en colecciones. En el CLI:
bw list organizations | jq -r '.[] | [.id, .name] | @tsv'
bw list collections | jq -r '.[] | [.id, .name] | @tsv'
bw list items --collectionid <id_coleccion>
# mover una entrada personal a la organización y la colección
echo '["<id_coleccion>"]' | bw encode | bw move "$ID" <id_organizacion>Roles de los miembros en una organización: Owner, Admin, User; roles personalizados (Custom) en Bitwarden están solo en el plan Enterprise. A nivel de colección la documentación de Bitwarden describe permisos «View items», «View items, hidden passwords», «Edit items», «Edit items, hidden passwords» y «Manage collection». Las contraseñas ocultas no protegen completamente: el autocompletado sigue funcionando y Bitwarden recomienda considerar que esa contraseña ya ha sido entregada al usuario. Compruebe en la interfaz de su versión de Vaultwarden qué niveles están implementados. Para automatización cree un usuario separado con acceso solo a la colección necesaria, en lugar de usar su propia cuenta con acceso a todo.
Script envoltorio
Un script que toma un secreto del almacén y lo pasa a un único comando sin escribir el secreto en disco ni pasarlo en los argumentos de línea de comandos:
#!/usr/bin/env bash
# with-secret: with-secret <entrada> <VARIABLE> -- comando [argumentos]
set -euo pipefail
set +x
item="$1"; var="$2"; shift 2
[ "${1:-}" = "--" ] && shift
: "${BW_SESSION:?Almacén sin desbloquear: export BW_SESSION=\"\$(bw unlock --raw)\"}"
value="$(bw get password "$item" --nointeraction)" || {
echo "No se pudo obtener $item" >&2; exit 1
}
# exec reemplaza el script por el comando: la variable existe solo en su entorno
export "$var=$value"
unset value BW_SESSION
exec "$@"with-secret db.example.ru PGPASSWORD -- psql -h db.example.ru -U app appdb--nointeraction evita que el CLI solicite la contraseña en medio del script: si el almacén está bloqueado, el comando fallará inmediatamente con «Vault is locked.». El valor del secreto no entra en los argumentos, en la salida ni en el historial; permanece en el entorno del comando ejecutado, y lo puede leer cualquier proceso del mismo usuario o root. El script elimina BW_SESSION del entorno antes de ejecutar el comando.
Si aun así tiene que introducir un comando con un secreto manualmente, no lo guarde en el historial. En bash:
export HISTCONTROL=ignoreboth # las líneas que comienzan con un espacio no se guardan
export MYSQL_PWD='<contraseña>' # espacio al inicio de la línea: el comando no se guardará
set +o history # desactivar el historial en la sesión actual
set -o history # activar de nuevoLa opción history existe solo en bash; en zsh las líneas con un espacio inicial no se guardan con setopt HIST_IGNORE_SPACE. El ejemplo pone la contraseña en el entorno, no en el argumento: HISTCONTROL oculta el comando solo del historial, pero el argumento sigue siendo visible en la lista de procesos. Lo más seguro es no escribir secretos en la línea de comandos. Cómo evitar fugas de secretos en Git está explicado en el artículo Desarrollo seguro: Parte 2 — Secretos en el código.
Errores típicos
«You are not logged in.» — no ha iniciado sesión o lo hizo con otro BITWARDENCLI_APPDATA_DIR. Compruebe bw status, y si hace falta bw config server y bw login.
«Vault is locked.» — el almacén está bloqueado y el CLI se ejecutó con --nointeraction; sin esa opción pedirá la contraseña maestra. Ejecute bw unlock --raw y exporte BW_SESSION.
Clave BW_SESSION inválida o antigua. Tras bw lock, bw logout o un nuevo desbloqueo la clave anterior deja de valer: los comandos dicen que el almacén está bloqueado o no pueden descifrar los datos. Desbloquee de nuevo y actualice la clave guardada en $XDG_RUNTIME_DIR.
«More than one result was found». — la cadena de búsqueda coincide con varias entradas. Use el ID de bw list items --search.
«Not found.» — la entrada no existe o el CLI aún no la ve: fue creada en otro cliente después de la última sincronización. Ejecute bw sync.
Error de certificado al bw login — el servidor usa el certificado de una CA interna. Indique NODE_EXTRA_CA_CERTS; no desactive la verificación.
Advertencia «Warning: Provided passwordenv … is not set» — la variable cuyo nombre pasó a --passwordenv está vacía o no fue pasada al proceso; en ese caso el CLI preguntará la contraseña, y con --nointeraction luego saldrá el error «Master password is required. Try again in interactive mode or provide a password file or environment variable.». Pase el nombre de la variable, no su valor: --passwordenv BW_PW, no --passwordenv "$BW_PW".
Para depurar la conexión con el servidor, el CLI imprime un log detallado con BITWARDENCLI_DEBUG=true. Antes de enviar ese log a alguien, compruebe que no contiene tokens.
// Tarea parecida
Si estás resolviendo algo parecido
Este artículo pertenece a uno de los temas principales de trabajo. Puedes seguir leyendo sobre el tema, ir a la página principal para entender a qué me dedico o abrir directamente los servicios.
Tema del artículo
Servidores e infraestructura
VPS, Linux, stack web, migraciones, hosting, bases de datos y operacion base.
Tareas frecuentes de este tema
- Migrar un sitio o servicio a un nuevo servidor
- Configurar Linux, Nginx, base de datos y copias de seguridad
- Entender por que el sistema funciona de forma inestable
// Siguiente paso
Si necesitas ayuda con este tema y no solo otro artículo, es mejor ir directo a la página del servicio. La página principal y la selección de materiales quedan como rutas secundarias.
Abrir servicios// Contact
¿Necesitas ayuda?
Escríbeme y te ayudaré a resolver el problema
Respondo en un día laborable (03:00-13:00 GMT)
O deje su solicitud aquí:
// Related