Episodes · EP002 · By design

Folio: By Design

Why you can trust a new secret manager: what Folio is built on, where your secrets go, how they travel, and how it stays easy to use.

EP001 showed what Folio is for. But a new secret manager asks for your most sensitive values, your tokens and your passwords, and being suspicious of one is fair. So don't take Folio on faith. This is how it is built, and why:

  1. Trusted. It is built on pass, gpg and git, and it is one bash script you can check and read.
  2. Secure. A secret goes straight to the one command that needs it, and nowhere else.
  3. Portable. Some items, or the whole store, travel as one locked file.
  4. Usable. Variable names come from the path, a project says what it needs in a vars file, a secret can go to the clipboard, and you pick how often the passphrase is asked.

Here is what is under your store, in one picture:

~/.gnupg · your GPG keyring🗝️ the store keypublic halfencrypts secrets, checks textssecret half 🔒decrypts secrets, signs textsgpg-agentremembers yourpassphrasefor a whileunlocks~/.folio · your folio storea pass store, with a git history.gpg-idwhich key: the store key's fingerprintreference it.git/every change, committed🔑 gh/token.gpga secret: encrypted to the key📄 gh/user.txt + .siga text: plain, and signed by the key🧑 youtype thepassphrasepinentrygpg's prompt, ina terminal or a window
▶
Rather watch? The same, in four parts, is a short video: flip through the slides.

Trusted: built on pass

Folio brings no vault of its own, no account and no service. It stands on a few plain pieces: your GPG key, a pass store, and git. folio init sets them up.

Your own GPG key

The store key lives in your GPG keyring (~/.gnupg), with any other keys you have. Like every GPG key, it has two halves. The public half encrypts, and checks signatures: anyone may have it. The secret half decrypts, and signs, and it is locked by the passphrase you chose. This is the sandbox's key, as gpg lists it (a post-quantum one: its encryption subkey is ML-KEM, ky768):

Folio
gpg --list-secret-keys --keyid-format none
sec brainpoolP384r1 2026-10-28 [SC] [expires: 2029-10-27]
C9406AB7E48726D265D45E4AD5DE5723219725DF
uid [ultimate] Demo User <demo@example.com>
ssb ky768_bp256 2026-10-28 [E]

A plain pass store, and its .gpg-id

The store is a folder, ~/.folio by default, kept apart from your own ~/.password-store. folio init makes it private (700): even encrypted, the names of your items and the plain texts would show to other users. A fresh store holds only this:

Folio
ls -A ~/.folio
.git .gitattributes .gpg-id
cat ~/.folio/.gpg-id
C9406AB7E48726D265D45E4AD5DE5723219725DF

.gpg-id is how the store knows its key: one line, the key's fingerprint, written by pass init. Everything in the store is encrypted to, or signed by, the key it names.

Secrets and texts

A secret is a <name>.gpg file, encrypted to the store key: exactly a pass entry. A text is a plain <name>.txt file, for a value that is not secret but must not be tampered with (a URL, a user name, a region). It is signed with the store key in <name>.txt.sig, so a text changed outside Folio, or signed by another key, is refused rather than used. The commands always say which kind they mean, so a secret is never shown by accident.

Which half of the key a command needs decides whether you are asked for the passphrase. Writing a secret only uses the public half; reading one, or writing a text, needs the secret half:

You…The key doesPassphrase?
add a secretencrypt (public half)no
read a secret, or run a command with onedecrypt (secret half)yes
add or edit a textsign (secret half)yes
read a textcheck the signature (public half)no
back up the storeexport the secret halfyes

Every change, in git

The store is a git repository, and every change is committed, by pass or by Folio. A removed item is still in the history. This is the sandbox's, after a first setup and a few more commands:

Folio
git -C ~/.folio log --oneline
13f452c (HEAD -> master) Remove gh/token-old from store.
25b183b Copy gh/token to gh/token-old.
5de2373 Rename gh/user to gh/login.
…
f696965 Add given password for gh/token to store.
cfa04a2 Add given text for gh/user to store.
d939fe6 Configure git repository for gpg file diff.
60859f8 Add current contents of password store.

One script you can check, and read

Folio is one bash script, folio: plain text from start to end. First check that the one you run is the one released. The install script checks the download for you; at any time after, go to where folio is, fetch the SHA256SUMS its release publishes, and check the file against it (on macOS, shasum -a 256 -c for sha256sum -c):

Folio
pushd "$(dirname "$(which folio)")"
~/.local/bin ~
version=$(folio version | cut -d" " -f2)
releases=https://github.com/NawaMan/EnvFolio/releases/download
curl -fsSL $releases/v$version/SHA256SUMS | sha256sum -c
folio: OK
popd
~

Then read it. It is plain, linear bash, written so that anyone can read it top to bottom and see that no secret is sent anywhere.

Or have an AI read it for you. Give it the file and ask: does any secret leave this machine, land in a file, or reach the screen when I did not ask? That is your own check, of the very file you run, not a promise from us.

Nothing locked in

folio runs pass, gpg and git for you, and that is all. And because the store is a plain pass store, pass itself still opens every secret in it. If you ever stop using Folio, nothing is locked in:

Folio
PASSWORD_STORE_DIR=~/.folio pass show gh/token
ghp_DEMO0000fake0000token

Secure: straight to the process

folio exec runs a command with your items as environment variables, the way op run and aws-vault exec do. The command gets them; nothing else does. Texts come by default, and secrets only when you say -s (--secrets):

Folio
folio exec -s gh -- release.sh
==| Releasing v1.2.0 |==
GH_USER : demo@example.com
GH_TOKEN: ✅ given
Publishing ...
...
--| Done |--

release.sh stands in for any script of yours. It uses what it is given: it prints the text, and only says that the secret is there. The secret never has to reach the screen.

  • Never on a command line, in a file, or on the screen, unless you ask to see one. A secret is read at a hidden prompt or from a pipe, and handed to pass on stdin. No option takes a secret as an argument, so none ends up in your shell history.
  • See before it runs. --names shows which variable would get which item, and stops; --debug shows it and runs; --confirm shows it and asks first. No value is read before that.
  • All or nothing. Every item is checked and read before the command starts. If one fails, the command does not run.

What it does not do: once a command has a secret in its environment, anything running as you can read it (/proc/<pid>/environ on Linux), so run only commands you trust. And Folio does not protect against someone who already runs code as you, or as root. Your secrets are as safe as your GPG key and its passphrase.

Portable: one locked file

folio export copies just the items a machine needs into one file, and the file is always locked: with a passphrase, or with --to, to the public key of where it is going, so it can travel through places you do not trust. Your store's own key never leaves your machine: each secret is encrypted again, to a key made for this export only, through a pipe, never touching the disk.

💻 your laptop
folio export -s --vars app2.vars -o app2.folio
✓ Items: 3 (texts: 1, secrets: 2)
✓ File: app2.folio

There, folio import brings the items into a store. Or skip the store: with --from, folio exec uses the file itself as the store. It is unpacked into a private temporary folder, read, and removed before the command starts; nothing is kept.

☁️ a server, or a cloud booth · no store
folio exec -s --from app2.folio --vars app2.vars -- deploy.sh
==| Super Cool App -- Deployment |==
...
--| Deploying is completed |--

For the whole store, key and all, there is folio backup and folio restore: one file, and back, on a new machine.

Usable

A secret manager you don't enjoy using is one you stop using. So:

An item's variable name comes from its path

/, - and . turn into _, then it is uppercased, and a top folder whose name starts with @ (a namespace) is dropped. No mapping to write:

ItemVariable
gh/tokenGH_TOKEN
@me/gh/tokenGH_TOKEN
gh/api-keyGH_API_KEY
gh/api+keynone: not a valid name, left out with a warning

A namespace lets you keep items in groups, such as the GitHub tokens of two accounts under @work/ and @me/, without the group's name ending up in the variable.

To pick the name yourself, write it on the command line:

folio exec --secrets GITHUB_TOKEN=gh/token -- gh release list

A vars file says what a project needs

A vars file names what a command needs, by its own names, and where each value comes from: @{name} is an item, ${NAME} a variable already set. Think of it as the project's .env.example: a record of which variables the application needs. It holds no value itself, so it can go in the repository with the code, while the values stay in your store:

# deploy.vars
GITHUB_TOKEN=@{gh/token}                  # gh/token, as GITHUB_TOKEN
AUTH=Bearer @{gh/token}                   # put into a longer value
REGION=@{aws/region:-${AWS_REGION}}       # with a fallback when the item is not there
@{aws/*}                                  # every item under aws/, each named by its path
folio check vars deploy.vars                      # check how it is written (no store needed)
folio exec --secrets --names --vars deploy.vars   # show where each variable would come from
folio exec --secrets --vars deploy.vars -- ./deploy.sh

With --vars, the command gets only what the file sets.

A secret to the clipboard, for a while

Some secrets go into a password box, not a command. -c copies one to the clipboard instead of showing it, and the clipboard is cleared after 45 seconds (PASSWORD_STORE_CLIP_TIME). A text can be copied too, and is not cleared.

Folio
folio show secret -c gh/token
Copied gh/token to clipboard. Will clear in 45 seconds.

The passphrase, three ways

Folio never asks for a passphrase itself. gpg does, through its agent: gpg-agent runs a small program, pinentry, that asks you, in the terminal or in a window. The agent then remembers the passphrase for its cache time, so the next folio, pass or gpg needs none. How often you type it is up to you:

WayAskedHow
Defaultonce, then not for a whilepinentry asks, gpg-agent remembers
Auto, a machine you trustneverFOLIO_STORE_PASSPHRASE_FILE=<file>: a file only you can read (chmod 600, or Folio refuses it)
Strict, a machine you trust lessevery command--fresh-passphrase, or FOLIO_FRESH_PASSPHRASE=1: the agent forgets it when each command starts and ends
  • Default: how long the agent remembers is default-cache-ttl and max-cache-ttl (seconds), in ~/.gnupg/gpg-agent.conf. For a window instead of the terminal, install a GUI pinentry (pinentry-gnome3, pinentry-qt, or pinentry-mac on macOS) and name it there:
    echo "pinentry-program $(command -v pinentry-gnome3)" >> ~/.gnupg/gpg-agent.conf
    gpgconf --kill gpg-agent
  • Auto: anyone who can read that file, or run commands as you, can open the store. Use it only where you would leave the store unlocked. The command exec runs does not get the variable.
  • Strict: exec and shell have the agent forget it before the command starts: they hold the values, not the passphrase.

Bottom line

Folio asks for your trust in the plainest way it can. Your secrets sit in a pass store, under your own GPG key, in one bash script you can read. They go straight to the command that needs them, and nowhere else. They travel as one locked file, and never with your key. And it stays easy to use: names from the path, a vars file per project, the clipboard, and the passphrase as often as you like. To make your own store and use it, start from its README.

Keep your secrets out of plain sight.

Links