CLI utility

Overview

Command line interface for retrieving passwords from the Passwork password manager and securely using them in scripts and commands.

Passwork CLI operates in two main modes:

• exec — retrieves passwords from Passwork, adds them to environment variables, and runs the specified command with access to these variables;
• api — provides direct access to the Passwork API, allowing execution of any API methods and receiving responses in JSON format.

Requirements

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

Installation

You can install the package directly from Github:

shell

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

Or via HTTPS:

shell

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

Common parameters

All commands support the following parameters:

Parameter	Environment variable	Description
--host	PASSWORK_HOST	Passwork server URL
--token	PASSWORK_TOKEN	API access token
--refresh-token	PASSWORK_REFRESH_TOKEN	Refresh token (optional)
--master-key	PASSWORK_MASTER_KEY	Master key for decryption
--no-ssl-verify		Disable SSL certificate verification

1. Execution mode (exec)

Retrieves passwords from Passwork, decrypts them, places them into environment variables, and runs the specified command with access to these variables.

Syntax

shell

passwork-cli exec [options] command_to_execute

Or using the --cmd parameter:

shell

passwork-cli exec [options] --cmd "command_to_execute"

Password identification

For the exec command, you must specify at least one of the following parameters:

Parameter	Description
--password-id	ID of one or multiple passwords (comma-separated)
--vault-id	ID of one or multiple vaults (comma-separated)
--folder-id	ID of one or multiple folders (comma-separated)
--tags	Tags to search passwords by (comma-separated)

How it works

1. Authentication: Connects to the Passwork server using the provided credentials;
2. Password Retrieval: Searches passwords by specified criteria (ID, vault, folder, tags);
3. Decryption: Decrypts found passwords using the master key;
4. Environment Creation: Forms environment variables from:
   • The main password value (variable name corresponds to the password name);
   • All custom fields of the record.
5. Command Execution: Runs the specified command in a new process with access to the environment variables.

Features

• Support for multiple passwords: Ability to use multiple passwords simultaneously;
• Access to custom fields: All custom fields are available as environment variables;
• Variable naming: Spaces and symbols are replaced with _;
• Docker-like syntax: The command can be specified immediately after CLI parameters;
• Exit code preservation: Returns the exit code of the executed command.

Use cases

• Database access: Connect without storing passwords in configuration;
• API authentication: Run scripts requiring tokens;
• Deployment: Execute scripts considering access to passwords of various services;
• Server administration: Perform tasks with privileges;
• CI/CD pipelines: Securely pass passwords to automated processes.

Usage examples

Retrieve a password and execute a command:

shell

# Export environment variables
export PASSWORK_HOST="https://passwork.example.com"
export PASSWORK_TOKEN="your_token"
export PASSWORK_MASTER_KEY="your_master_key"

# Retrieve password by ID and run MySQL client
passwork-cli exec --password-id "db_password_id" mysql -u admin -h localhost -p $DB_PASSWORD database_name

Retrieve multiple passwords from a folder:

shell

# Retrieve all passwords from the project folder and run deploy script
passwork-cli exec --folder-id "project_folder_id" ./deploy.sh

Using different identifiers:

shell

# Retrieve passwords by ID, tags, and from folder
passwork-cli exec \
  --password-id "specific_password_id" \
  --tags "production,database" \
  --folder-id "api_credentials" \
  ./complex_deployment.sh

Shell commands:

shell

# For shell commands, use --cmd
passwork-cli exec --password-id "server_creds" --cmd "ssh user@server 'cat /var/log/app.log | grep ERROR' > local_errors.log"

Connecting to a server with a self-signed certificate:

shell

# Disable SSL verification
passwork-cli exec --no-ssl-verify --password-id "test_server_password" ssh [email protected]

2. API mode

Allows direct calls to the Passwork API with responses in JSON format.

Syntax

shell

passwork-cli api [options]

API parameters

The api command requires the following parameters:

Parameter	Description
--method	HTTP method (GET, POST, PUT, DELETE, PATCH)
--endpoint	API path (e.g., v1/vaults)
--params	JSON string with parameters (optional)
--field	Field name to extract from the response (optional)

How it works

1. Authentication: Connects to the Passwork server;
2. Request Formation: Creates an HTTP request with the specified path and method;
3. Request Sending: Sends the request with the necessary authorization headers;
4. Response Handling: Receives and parses the API response;
5. Filtering (optional): Extracts the specified field using --field;
6. Output: The result is output in JSON format.

Usage examples

Get a list of all vaults:

shell

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

Get a specific password and extract only the name:

shell

passwork-cli api --method GET --endpoint "v1/items/password_id" --field "name"

Search passwords by tags and get their names:

shell

passwork-cli api \
  --method GET \
  --endpoint "v1/items/search" \
  --params '{"tags":["api","production"]}' \
  --field "name"

Refresh the access token:

shell

passwork-cli api \
  --host "https://passwork.example.com" \
  --token "your_expired_token" \
  --refresh-token "your_refresh_token" \
  --method POST \
  --endpoint "v1/sessions/refresh" \
  --field "token"

Using with a self-signed certificate:

shell

passwork-cli api --no-ssl-verify --method GET --endpoint "v1/user/profile"

Security

• Credentials are not saved to disk;
• Commands with passwords do not appear in shell history;
• Passwords are accessible only inside the running process;
• It is recommended to use environment variables to store credentials.

Examples

Additional scenario examples are located in the examples_cli directory.