CLI and secret injection

Passwork CLI is the primary tool for secret injection in shell scripts and CI/CD pipelines. It retrieves secrets from Passwork, decrypts them locally (handling CSE transparently), and makes them available as environment variables or standard output — without the secret ever appearing in shell history or script files.

---

Installation

PyPI

pip install passwork-python

GitHub (SSH)

pip install git+ssh://[email protected]:passwork-me/passwork-python.git

GitHub (HTTPS)

pip install git+https://github.com/passwork-me/passwork-python.git

Requirements:

• Python 3.10+
• requests>=2.31.0,
• python-dotenv>=1.0.0
• cryptography>=42.0.0
• pbkdf2>=1.3

Docker image

For containerized environments and CI/CD runners, use the official Docker image:

docker pull passwork/passwork-cli:latest

---

Authentication environment variables

All CLI modes read credentials from environment variables. Set these before calling any passwork-cli command:

export PASSWORK_HOST="https://passwork.example.com"
export PASSWORK_TOKEN="<access_token>"
export PASSWORK_REFRESH_TOKEN="<refresh_token>"   # optional, enables auto-renewal
export PASSWORK_MASTER_KEY="<master_key>"          # required only if CSE is enabled

Alternatively, pass them as flags: --host, --token, --refresh-token, --master-key.

No CSE

If client-side encryption is disabled on your Passwork instance, omit PASSWORK_MASTER_KEY and --master-key. The CLI works without it.

---

Exec mode — inject secrets into a process

exec is the core mode for secret injection. It fetches the specified records, decrypts them, sets them as environment variables, and runs the command you specify with those variables in scope. The variables exist only for the duration of the process — they are never written to disk or shell history.

Syntax

passwork-cli exec [selection parameters] command_to_execute

Selection parameters

Parameter	Description
--password-id <id>	Single item ID (or multiple comma-separated)
--folder-id <id>	All items from a folder (or multiple comma-separated folders)
--vault-id <id>	All items from a vault
--tags <tag1,tag2>	All items matching the given tags

Variable naming

The item's name becomes the environment variable name. Spaces and special characters are replaced with underscore _. Custom field names become their own variables.

Record named POSTGRES_PASSWORD with custom field DB_HOST → injects POSTGRES_PASSWORD and DB_HOST.

Examples

Run a database migration with credentials from a folder:

shell

passwork-cli exec --folder-id "prod-databases-folder-id" \
  ./migrate.sh

Run a command that needs specific DB credentials by item ID:

shell

passwork-cli exec --password-id "postgres-order-svc-id" \
  psql -h "$DB_HOST" -U "$DB_USER" -d orders

Run a complex command with pipes (use --cmd):

shell

passwork-cli exec --password-id "server-creds-id" \
  --cmd "ssh user@server 'journalctl -u app | tail -100' > errors.log"

Fetch all production API credentials by tag:

shell

passwork-cli exec --tags "production,external-api" \
  ./sync-integrations.sh

---

Get mode — retrieve a specific value

get decrypts a single field from an item and writes it to stdout. Use this when a script needs to capture a secret value into a variable.

passwork-cli get --password-id "<item_id>" [--field <field_name>]

Without --field, get returns the password field. With --field, it returns the named custom field.

shell

# Store the value in a variable (does not appear in process list)
DB_PASS=$(passwork-cli get --password-id "postgres-prod-id")

# Get a specific custom field
AWS_KEY=$(passwork-cli get --password-id "aws-creds-id" --field "AWS_SECRET_ACCESS_KEY")

Avoid echoing secrets

Never echo $DB_PASS in scripts. Use the value directly in the command that needs it. Shell history and CI/CD logs capture command arguments — not environment variable values.

---

Update mode — rotate a secret value

update writes a new value to a specified field in an existing Passwork item. Use this in rotation scripts after updating the secret in the target system.

passwork-cli update --password-id "<item_id>" --password "<new_value>"

For custom fields:

passwork-cli update --password-id "<item_id>" \
  --field "AWS_SECRET_ACCESS_KEY" --value "<new_key>"

See Secret rotation for complete rotation workflows.

---

API mode — raw API calls

api sends an arbitrary API request and returns the JSON response. Use it for operations not covered by the other modes, or to inspect Passwork data from scripts.

shell

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

# Get a specific item
passwork-cli api --method GET --endpoint "v1/items/<item_id>"

---

Docker image

Use passwork/passwork-cli:latest in environments where installing Python packages is not practical.

One-shot

docker run --rm \
  -e PASSWORK_HOST="https://passwork.example.com" \
  -e PASSWORK_TOKEN="$PASSWORK_TOKEN" \
  -e PASSWORK_MASTER_KEY="$PASSWORK_MASTER_KEY" \
  -v "$(pwd)":/app -w /app \
  passwork/passwork-cli:latest \
  exec --folder-id "$SECRETS_FOLDER_ID" ./deploy.sh

Docker Compose

services:
  deploy:
    image: passwork/passwork-cli:latest
    environment:
      PASSWORK_HOST: ${PASSWORK_HOST}
      PASSWORK_TOKEN: ${PASSWORK_TOKEN}
      PASSWORK_MASTER_KEY: ${PASSWORK_MASTER_KEY}
    volumes:
      - .:/app
    working_dir: /app
    command: exec --folder-id "${SECRETS_FOLDER_ID}" ./deploy.sh

The Docker image runs as a non-root user. For CI/CD pipeline usage, see CI/CD patterns.

For full CLI documentation, see CLI utility and Docker container for CLI.

LLM version