Scanning of encrypted notes is supported if you have GnuPG installed globally, encrypted as an armored text file and named with the double extension .md.asc

Given our example encrypted file:

uid: f7c06418-f6de-415d-90e1-8850f440205f
sid: github-secrets
  - john
  - bots/ci
    value: ghp_ZxISAxJq7111u81kPwr1vU3JR
    expires: 30d
    target: tf-api

some notes

# ci-cd demo
id: ci-bot
value: 18F02xPLxbFE

This token is used by the CI-CD bot

Preparing your tools

Most editors have a GPG plugin to edit encrypted files directly. I use quite often the one for Vim since it can auto decrypt a file and auto encrypt again any modification.

Git can be configured to show diffs of encrypted files.


The recipients field makes explicit for the editor who has access, and helps the parsing tool to check if they are consistent. Some encryption tools like gpg encode this in the message, others like age don’t. In either case if we are going to work with plain files it is important making this information clear.

tfc secrets fsck

Extract encoded key values

You can query any value within a note with an id and query path

tfc kv {file id} {query-path}

Since the sample note has a sid we can use it instead the id to get the value for our scripts.

GITHUB_TOKEN=$(tfc kv github-secrets tokens.worker-2.value)

I try to keep all api tokens from a service within a file, so I get a good overview of my authorization landscape. In some cases I want to annotate some token. A Yaml comment works just fine, but if I need to extend myself I opt for moving the value into a section with an id or lid mark. This can be used as part of the query path.

tfc kv github-secrets ci-bot.value

Encrypted secret sets

When using target: tf-api to mark users of that secret, it is possible to export them all into a single JSON output you can use to generate app specific secrets.

$ tfc secrets target tf-api
  "github-secrets/worker-2": "ghp_ZxISAxJq7111u81kPwr1vU3JR",
  "cloudflare-secrets/deploy": "q7111u81kPwr1vU3JR"

You could encrypt and send the file to your server, or create a script to upload them into your provider secrets manager, like AWS Systems Manager Parameter Store or Vault

In general, you will face two encrypted sets of secrets. A group of encrypted markdown notes for the human operators to document their secrets, and a encrypted set of token values specific to the app that needs them.