---
name: elpass-credentials
description: Safely locate and use credentials stored in Elpass through its macOS CLI. Use when an agent needs a login, password, domain, username, API token, or custom credential field for another command or automation while keeping credential values out of chat, logs, and visible tool output.
---

# Elpass Credentials

Use this CLI exactly:

```text
/Applications/Elpass.app/Contents/Applications/elpass-cli
```

Treat every fetched value as secret, including usernames, domains, and custom fields.

## Required workflow

1. Use `search` to locate the item UUID. This is pre-authorized and does not require separate user consent:

   ```sh
   '/Applications/Elpass.app/Contents/Applications/elpass-cli' search '<keyword>'
   ```

   Search by the smallest useful title or domain fragment. If several items plausibly match, ask the user which item to use. Do not guess.

2. Prefer `fetch` to retrieve only the field required by the task:

   ```text
   elpass-cli fetch <item-uuid> <field>
   ```

   Supported built-in fields are `password`, `username`, and `domain`. A custom field title may be used as the field name.

3. Connect `fetch` directly to the program that needs the value. Never run it as a standalone command when its stdout would be returned to the model or shown to the user.

4. Complete the requested operation, then report only that the credential was used successfully or that the operation failed. Never include the fetched value in the response.

## Safe transfer patterns

Prefer a consumer that accepts the value through stdin:

```sh
'/Applications/Elpass.app/Contents/Applications/elpass-cli' fetch '<item-uuid>' password |
  consumer-command --password-stdin
```

If the consumer only accepts an environment variable, scope it to a single non-debug shell invocation:

```sh
CONSUMER_SECRET_ENV="$('/Applications/Elpass.app/Contents/Applications/elpass-cli' fetch '<item-uuid>' password)" consumer-command
```

Replace `CONSUMER_SECRET_ENV` with the environment variable the consumer actually reads. Do not enable shell tracing. Prefer stdin over environment variables, and prefer environment variables over command-line arguments.

If the consumer cannot accept the credential without exposing it in argv, logs, tool output, or a persistent file, stop and ask the user for a safer integration method.

## Prohibited disclosure

- Never paste, quote, summarize, transform, or otherwise reproduce fetched values in chat.
- Never print them with `echo`, `printf`, `cat`, `tee`, verbose/debug output, or error diagnostics.
- Never place them directly in a command-line argument.
- Never store them in source files, task artifacts, shell history, logs, or ordinary temporary files.
- Never return raw CLI stdout as tool output.
- Never fetch private keys, passkey private material, OTP secrets, or raw OTP URLs. Elpass may reject these fields; do not attempt to bypass that policy.

## `get` requires explicit consent

Avoid `get`: it prints multiple item fields and can disclose more information than the task needs.

Before every use of `get`, obtain explicit user consent that identifies the item and explains that multiple fields will be printed. Approval to use a credential or to run `fetch` is not approval to run `get`.

Never add `--show-sensitive` unless the user separately and explicitly approves showing sensitive fields. Even after approval, do not copy `get` output into the conversation.

## User verification

Elpass may require the user to approve the request with Touch ID, Apple Watch, or the master password. The CLI then writes this status to stderr:

```text
elpass-cli: Waiting for user confirmation in Elpass. Complete the verification prompt to continue.
```

Treat this as an in-progress request, not an error. Keep the process running and tell the user to complete the Elpass prompt if necessary. Do not retry, start parallel requests, or terminate the command while verification is pending.

Use the final exit status to determine success. Preserve stdout for the credential-to-consumer data path and stderr for status and errors.
