# Read secrets from an external secret manager (https://yoink.is/docs/how-to/external-secrets)

With `provider: command`, yoink runs a command and reads the secrets bundle from its stdout. Use the section for the secret manager that you already run.

## Before you start

- Make sure that the command prints only the bundle to stdout. Send diagnostics to stderr (`>&2`).
- Make sure that the auth token of the tool is in the environment. yoink forwards only an [allowlist of variables](/docs/reference/secrets#spawn-environment) to the command.
- If you need pipes or env-var expansion, put the call in a shell script. yoink runs the command without a shell.

For the dotenv and JSON bundle formats, see the [format reference](/docs/reference/secrets#format-reference).

## sops

1. Run `brew install sops` on your laptop and on the CI runner.
2. Configure `.sops.yaml` with the encryption recipients (for example an age key or a KMS ARN).
3. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["sops", "-d", "--output-type=dotenv", "secrets.enc.yaml"]
```

To edit the secrets, run `sops edit secrets.enc.yaml`. yoink does not wrap this command.

For the trade-offs between sops and `provider: age`, see [Secrets](/docs/explanation/secrets#sops).

## Doppler

1. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["doppler", "secrets", "download", "--no-file", "--format", "env"]
```

2. In CI, set the `DOPPLER_TOKEN` env var to a service token that has the scope of the correct config.

The runner does not need `doppler login`.

## Infisical CLI

1. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command:
    - infisical
    - export
    - --env=prod
    - --projectId=YOUR_PROJECT_ID
    - --format=dotenv
```

2. For auth, set `INFISICAL_TOKEN` (machine identity) or use a logged-in `infisical login` session.
3. If the instance is self-hosted, add `--domain=https://infisical.your.domain` to the argv.

PEM certs and private keys pass through unchanged. Infisical emits them in single quotes across multiple lines, and the dotenv parser of yoink reads that shape. A wrapper script is not necessary.

## HashiCorp Vault

1. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["sh", "-c", "vault kv get -format=json -field=data secret/yoink/prod"]
  format: json
```

2. For auth, set `VAULT_ADDR` and `VAULT_TOKEN`, or use AWS or OIDC roles.

`-field=data` makes Vault print the flat KV data as one JSON object on stdout.

## AWS Secrets Manager

1. Store the value in the SecretString as a JSON object (`{"DB_URL":"...","API_KEY":"..."}`) or as a dotenv blob.
2. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command:
    - sh
    - -c
    - "aws secretsmanager get-secret-value --secret-id yoink/prod --query SecretString --output text"
  format: auto
```

Auth comes from the IAM role of the runner.

## 1Password

1Password holds structured items, not a flat namespace. A small wrapper script emits them as dotenv.

1. Write the wrapper script:

```sh
# bin/yoink-secrets.sh — operator-owned, gitignored alongside yoink.yaml
#!/usr/bin/env bash
set -euo pipefail
op read "op://Engineering/yoink-prod/DATABASE_URL"        | sed 's/^/DATABASE_URL=/'
op read "op://Engineering/yoink-prod/JWT_SIGNING_KEY"     | sed 's/^/JWT_SIGNING_KEY=/'
op read "op://Engineering/yoink-prod/STRIPE_SECRET_KEY"   | sed 's/^/STRIPE_SECRET_KEY=/'
```

2. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["./bin/yoink-secrets.sh"]
```

3. In CI, set the `OP_SERVICE_ACCOUNT_TOKEN` env var to the token of a 1Password service account.

As an alternative to the wrapper script, use `op inject` with a template:

```sh
# secrets.tpl
DATABASE_URL={{ op://Engineering/yoink-prod/DATABASE_URL }}
JWT_SIGNING_KEY={{ op://Engineering/yoink-prod/JWT_SIGNING_KEY }}
```

```yaml
secrets:
  provider: command
  command: ["op", "inject", "-i", "secrets.tpl"]
```

## Bitwarden

1. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["bws", "secret", "list", "PROJECT_UUID", "--output", "env"]
```

2. For auth, set `BWS_ACCESS_TOKEN`.

## A static dotenv file (for local development)

Use this config to keep the `provider: command` schema in local development, with a plain file as the source.

1. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["cat", ".env.local"]
```

2. Add `.env.local` to `.gitignore`.

## Layered: command on top of age

yoink does not merge providers. A wrapper script that prints the two bundles in sequence gives the same result.

`yoink secrets show` works only with `provider: age`. Thus the age block goes into a second config file.

1. Write a second config file that holds only the age block:

```yaml
# yoink.age.yaml
secrets:
  provider: age
  recipients: [age1…]
```

2. Write the wrapper script:

```sh
# bin/yoink-secrets.sh
yoink --config yoink.age.yaml secrets show --reveal   # age-decrypted dotenv (committed)
op inject -i ops-overrides.tpl                        # 1Password-managed runtime tweaks
```

3. Add this config to `yoink.yaml`:

```yaml
secrets:
  provider: command
  command: ["./bin/yoink-secrets.sh"]
```

Later lines override earlier lines, because the dotenv parser keeps the last value for each key.

yoink does not forward `YOINK_AGE_KEY` or `YOINK_AGE_KEY_FILE` to the command. The age identity must be in `~/.config/yoink/keys/`, or the script must set the variable.

## Make sure that it works

Run `yoink up`. yoink runs the command one time for each `yoink up` and injects the values as env vars into the containers.

If the command exits non-zero, yoink stops and shows the stderr of the command. If the bundle is malformed, yoink stops with a parse error.

## See also

- [Secrets](/docs/explanation/secrets): when `provider: command` is a better fit than the age default, and the trade-offs of sops.
- [Secrets resolution and bundle formats](/docs/reference/secrets): the rules for the command, the spawn environment, and the dotenv and JSON formats.
- [Config reference](/docs/reference/config): the `secrets:` schema.
- [Sealed secrets workflow](/docs/how-to/sealed-secrets-workflow): the tasks for the `provider: age` default.
