# passwordstore – manage passwords with passwordstore.org’s pass utility

- Synopsis

- Parameters

- Examples

- Return Values

- Status

## Synopsis

- Enables Ansible to retrieve, create or update passwords from the passwordstore.org pass utility. It also retrieves YAML style keys stored as multilines in the passwordfile.

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
_terms - / required |  |  | query key

backup
boolean
added in 2.7

Choices:
- no ←
- yes

Used with `overwrite=yes`. Backup the previous password in a subkey.

create
boolean

Choices:
- no ←
- yes

Create the password if it does not already exist.

directory - |  | env:PASSWORD_STORE_DIR | The directory of the password store.
length integer | Default: 16 |  | The length of the generated password

nosymbols
boolean
added in 2.8

Choices:
- no ←
- yes

use alphanumeric characters

overwrite
boolean

Choices:
- no ←
- yes

Overwrite the password if it does already exist.

passwordstore - | Default: "~/.password-store" |  | location of the password store

returnall
boolean

Choices:
- no ←
- yes

Return all the content of the password, not only the first line.

subkey - | Default: "password" |  | Return a specific subkey of the password. When set to `password`, always returns the first line.
userpass - |  |  | Specify a password to save, instead of a generated one.

## Examples

    # Debug is used for examples, BAD IDEA to show passwords on screen
    - name: Basic lookup. Fails if example/test doesn't exist
      debug:
        msg: "{{ lookup('passwordstore', 'example/test')}}"

    - name: Create pass with random 16 character password. If password exists just give the password
      debug:
        var: mypassword
      vars:
        mypassword: "{{ lookup('passwordstore', 'example/test create=true')}}"

    - name: Different size password
      debug:
        msg: "{{ lookup('passwordstore', 'example/test create=true length=42')}}"

    - name: Create password and overwrite the password if it exists. As a bonus, this module includes the old password inside the pass file
      debug:
        msg: "{{ lookup('passwordstore', 'example/test create=true overwrite=true')}}"

    - name: Create an alphanumeric password
      debug: msg="{{ lookup('passwordstore', 'example/test create=true nosymbols=true') }}"

    - name: Return the value for user in the KV pair user, username
      debug:
        msg: "{{ lookup('passwordstore', 'example/test subkey=user')}}"

    - name: Return the entire password file content
      set_fact:
        passfilecontent: "{{ lookup('passwordstore', 'example/test returnall=true')}}"

## Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key | Returned | Description
--- | --- | ---
_raw - |  | a password

## Status

- This lookup is not guaranteed to have a backwards compatible interface. [preview]

- This lookup is maintained by the Ansible Community. [community]

### Authors

- Patrick Deelman <patrick@patrickdeelman.nl>

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.