cli

---

path: secret-management/cli.mdx title: Gestión de secretos mediante passwork-cli slug: /secret-management/cli pagination_next: secret-management/python-sdk pagination_prev: secret-management/concepts sidebar_position: 3 description: >- Cómo utilizar la utilidad passwork-cli para obtener y actualizar secretos de Passwork e inyectarlos en variables de entorno y comandos. keywords:

• Passwork
• passwork-cli
• CLI
• secrets
• CI/CD
• environment variables

---

Qué es passwork-cli

passwork-cli es una herramienta de línea de comandos para interactuar con los secretos de Passwork. Capacidades principales:

Funcionalidad	Descripción
Obtención de secretos	Obtener contraseñas, campos y códigos TOTP por ID de registro
Inyección en el entorno	Ejecutar comandos con secretos cargados en variables de entorno
Actualización de secretos	Modificar contraseñas y campos — útil para rotación y automatización
Acceso directo a la API	Ejecutar solicitudes HTTP arbitrarias contra Passwork

Zero-Knowledge

passwork-cli gestiona el cifrado localmente: el servidor de Passwork almacena solo datos cifrados, mientras que el descifrado y cifrado ocurren en su máquina. Incluso si el tráfico de red es interceptado o el servidor se ve comprometido, los atacantes no pueden acceder a sus secretos.

Instalación

Paquete Python (pip)

passwork-cli se distribuye como parte del conector Python. Instale con pip:

# PyPI
pip install passwork-python

# Or from GitHub via SSH
pip install git+ssh://[email protected]:passwork-me/passwork-python.git

# Or from GitHub via HTTPS
pip install git+https://github.com/passwork-me/passwork-python.git

Una vez instalado, el comando passwork-cli estará disponible en su terminal.

Imagen Docker

Para entornos de CI/CD o servidores sin Python, utilice la imagen Docker:

docker run --rm \
  -e PASSWORK_HOST="https://passwork.example.com" \
  -e PASSWORK_TOKEN="your_access_token" \
  -e PASSWORK_MASTER_KEY="your_master_key" \
  passwork/passwork-cli exec --password-id "<item-id>" ./deploy.sh

Consulte también: Contenedor Docker para CLI.

Configuración

Configure passwork-cli a través de variables de entorno:

Variable	Descripción	Obligatorio
PASSWORK_HOST	URL del servidor Passwork	Sí
PASSWORK_TOKEN	Token de acceso para autenticación	Sí
PASSWORK_MASTER_KEY	Clave maestra para el descifrado (si aplica)	Depende de la configuración

tip

En CI/CD, almacene PASSWORK_TOKEN y PASSWORK_MASTER_KEY como variables protegidas (GitLab CI Variables, GitHub Secrets, etc.) — nunca las incluya en su repositorio.

Modos de operación

passwork-cli ofrece cuatro modos. Elija según su tarea:

Modo	Propósito	Cifrado	Caso de uso típico
exec	Ejecutar un comando con secretos en ENV	Del lado del cliente	CI/CD, scripts de despliegue
get	Mostrar un único valor en STDOUT	Del lado del cliente	Scripts bash, consultas ad-hoc
update	Modificar campos del registro	Del lado del cliente	Rotación de contraseñas
api	Enviar solicitudes HTTP directas a la API	Manual	Automatización compleja, informes

info

Los modos exec, get y update gestionan el cifrado automáticamente. El modo api devuelve respuestas API sin procesar — usted gestiona el cifrado por su cuenta.

Documentación completa de cada modo: Utilidad CLI.

exec — ejecutar comandos con secretos

Obtiene secretos, los convierte en variables de entorno y ejecuta el comando especificado. Los secretos existen solo durante la duración de ese comando.

# Run deploy script using secrets from a folder
passwork-cli exec --folder-id "<folder-id>" ./deploy.sh

# Run using secrets from a specific record
passwork-cli exec --password-id "<item-id>" ./app

Utilice cuando: ejecute pipelines de CI/CD, scripts de despliegue o aplicaciones que necesiten secretos.

Detalles: modo exec.

get — obtener un único valor

Muestra un valor descifrado en STDOUT. Ideal para consultas rápidas en scripts.

# Retrieve password
passwork-cli get --password-id "<item-id>"

# Retrieve a custom field
passwork-cli get --password-id "<item-id>" --field API_KEY

# Retrieve a TOTP code
passwork-cli get --password-id "<item-id>" --totp

Utilice cuando: necesite un valor en un script bash o quiera generar un código TOTP.

Detalles: modo get.

update — modificar secretos

Cambia campos del registro: contraseña, login, URL, descripción, etiquetas o campos personalizados.

# Update password
passwork-cli update --password-id "<item-id>" --password "new-password"

# Update a custom field
passwork-cli update --password-id "<item-id>" --custom-field "API_KEY=new-api-key"

Utilice cuando: rote contraseñas, actualice claves después de la regeneración o realice actualizaciones masivas.

Detalles: modo update.

api — solicitudes HTTP directas

Envía solicitudes arbitrarias a Passwork API y devuelve JSON.

# List vaults
passwork-cli api --method GET --endpoint "v1/vaults"

# Search by tags
passwork-cli api --method GET --endpoint "v1/items/search" \
  --params '{"tags":["infrastructure","production"]}'

Utilice cuando: construya automatización compleja, genere informes o gestione operaciones no cubiertas por otros modos.

Detalles: modo api.

Ejemplos prácticos

CI/CD: despliegue con secretos

Un escenario común — ejecutar un script de despliegue que obtiene secretos de Passwork.

GitLab CI:

deploy:
  image: passwork/passwork-cli
  variables:
    PASSWORK_HOST: $PASSWORK_HOST
    PASSWORK_TOKEN: $PASSWORK_TOKEN
    PASSWORK_MASTER_KEY: $PASSWORK_MASTER_KEY
  script:
    - passwork-cli exec --folder-id "$SECRETS_FOLDER_ID" ./deploy.sh

GitHub Actions:

- name: Deploy with secrets
  run: |
    docker run --rm \
      -e PASSWORK_HOST="${{ secrets.PASSWORK_HOST }}" \
      -e PASSWORK_TOKEN="${{ secrets.PASSWORK_TOKEN }}" \
      -e PASSWORK_MASTER_KEY="${{ secrets.PASSWORK_MASTER_KEY }}" \
      -v $(pwd):/app -w /app \
      passwork/passwork-cli exec --folder-id "${{ vars.SECRETS_FOLDER_ID }}" ./deploy.sh

Rotación de una contraseña de base de datos

Genere una nueva contraseña, aplíquela a la base de datos y guárdela de nuevo en Passwork.

#!/bin/bash
set -e

# Generate a fresh password
NEW_PASS=$(openssl rand -base64 32)

# Apply to PostgreSQL
psql -h db.prod.internal -U postgres -c \
  "ALTER ROLE backend_svc WITH PASSWORD '${NEW_PASS}';"

# Store in Passwork
passwork-cli update \
  --password-id "<item-id>" \
  --password "${NEW_PASS}"

echo "Password rotated successfully"

Obtención de un secreto en un script bash

Cuando necesita solo un valor:

# Grab the DB password and use it immediately
DB_PASS=$(passwork-cli get --password-id "<item-id>")
psql -h db.internal -U webapp -W "$DB_PASS" -d orders -c "SELECT 1"

# Get an API key from a custom field
STRIPE_KEY=$(passwork-cli get --password-id "<item-id>" --field STRIPE_SECRET)
curl -H "Authorization: Bearer $STRIPE_KEY" https://api.stripe.com/v1/charges

Docker Compose con secretos

Inicie contenedores con secretos inyectados mediante exec:

# Start docker compose with secrets in the environment
passwork-cli exec --folder-id "<folder-id>" docker compose up -d

Dentro de docker-compose.yml, los secretos están disponibles como variables de entorno:

services:
  api:
    image: order-service:latest
    environment:
      - MYSQL_HOST=${MYSQL_HOST}
      - MYSQL_USER=${MYSQL_USER}
      - MYSQL_PASSWORD=${MYSQL_PASSWORD}