Managing secrets via passwork-cli

What is passwork-cli

passwork-cli is a command-line tool for interacting with Passwork secrets. Key capabilities:

Feature	Description
Secret retrieval	Fetch passwords, fields, and TOTP codes by record ID
Environment injection	Run commands with secrets loaded into environment variables
Secret updates	Modify passwords and fields — useful for rotation and automation
Direct API access	Execute arbitrary HTTP requests against Passwork

Zero-Knowledge

passwork-cli handles encryption locally: the Passwork server stores only encrypted data, while decryption and encryption occur on your machine. Even if network traffic is intercepted or the server is compromised, attackers cannot access your secrets.

Installation

Python package (pip)

passwork-cli ships as part of the Python connector. Install with 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

Once installed, the passwork-cli command is available in your terminal.

Docker image

For CI/CD environments or servers without Python, use the Docker image:

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

See also: Docker container for CLI.

Configuration

Configure passwork-cli through environment variables:

Variable	Description	Required
PASSWORK_HOST	Passwork server URL	Yes
PASSWORK_TOKEN	Access token for authentication	Yes
PASSWORK_MASTER_KEY	Master key for decryption (if applicable)	Depends on setup

tip

In CI/CD, store PASSWORK_TOKEN and PASSWORK_MASTER_KEY as protected variables (GitLab CI Variables, GitHub Secrets, etc.) — never commit them to your repository.

Operating modes

passwork-cli offers four modes. Choose based on your task:

Mode	Purpose	Encryption	Typical use case
exec	Run a command with secrets in ENV	Client-side	CI/CD, deploy scripts
get	Output a single value to STDOUT	Client-side	Bash scripts, ad-hoc queries
update	Modify record fields	Client-side	Password rotation
api	Send raw HTTP requests to the API	Manual	Complex automation, reports

info

Modes exec, get, and update handle encryption automatically. Mode api returns raw API responses — you manage encryption yourself.

Full documentation for each mode: CLI utility.

exec — run commands with secrets

Fetches secrets, converts them to environment variables, and executes the specified command. Secrets exist only for the duration of that command.

# 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

Use when: running CI/CD pipelines, deploy scripts, or applications that need secrets.

Details: exec mode.

get — retrieve a single value

Outputs a decrypted value to STDOUT. Ideal for quick lookups in 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

Use when: you need one value in a bash script or want to generate a TOTP code.

Details: get mode.

update — modify secrets

Changes record fields: password, login, URL, description, tags, or custom fields.

# 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"

Use when: rotating passwords, refreshing keys after regeneration, or making batch updates.

Details: update mode.

api — direct HTTP requests

Sends arbitrary requests to the Passwork API and returns 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"]}'

Use when: building complex automation, generating reports, or handling operations not covered by other modes.

Details: api mode.

Practical examples

CI/CD: deploying with secrets

A common scenario — run a deployment script that pulls secrets from 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

Rotating a database password

Generate a new password, apply it to the database, and save it back to 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"

Fetching a secret in a bash script

When you need just one value:

# 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 with secrets

Launch containers with secrets injected via exec:

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

Inside docker-compose.yml, secrets are available as environment variables:

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

LLM version