Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-CRED(1)                      User Commands                     HEE-CRED(1)

NAME
       hee-cred  - real, minimal sealed credential store (GPG, or age for TPM-
       bound secrets)

SYNOPSIS
       hee cred -seal ACCOUNT -recipients ID[,ID...]  [-dir PATH]
       hee cred -seal ACCOUNT -recipients ID[,ID...]  -genfrom  TERM  [-blocks
       N] [-root PATH]
       hee  cred  -seal  ACCOUNT  -backend  age -recipients RECIPIENT[,RECIPI‐
       ENT...]  [-dir PATH]
       hee cred -seal NAME -backend age -passphrase [-any] [-dir PATH] <  KEY‐
       FILE
       hee cred -install-keys -dir PATH [-account NAME] [-force]
       hee  cred -pass ACCOUNT -exec COMMAND [ARGS...]  [-dir PATH] [-identity
       FILE]
       hee cred -github-app ACCOUNT  [-key  FILE  [-force]]  [-registry  FILE]
       [-dir PATH]
       hee  cred  -run  ACCOUNT -github-token GRANT [-registry FILE] [-as VAR]
       -exec COMMAND [ARGS...]
       hee cred -reseal ACCOUNT|all -add-recipients ID[,ID...]  [-dir PATH]
       hee cred -reseal ACCOUNT|all [-dir PATH]

DESCRIPTION
       hee-cred stores secrets as ciphertext-only files under .hee/secrets/AC‐
       COUNT.gpg, or .hee/secrets/ACCOUNT.age for the age backend,  and  never
       lets  a decrypted value reach an agent's own visible output.  Retrieval
       is exec-only: the secret is injected into a single child process's  en‐
       vironment and nowhere else.

       -seal  (typed)  reads  the secret from an interactive hidden prompt. It
       refuses to run at all if stdin isn't a real terminal  --  deliberately,
       so a secret can never be piped in from a chat, log, or script.

       -seal  -genfrom  instead  pulls  real words out of a local media corpus
       matching TERM, joins them into a passphrase.  Still  never  printed  --
       flows straight into the same GPG encrypt call as a typed secret.

       -seal  -backend  age  encrypts with age(1) to age recipients instead of
       GPG keys. An age-plugin-tpm recipient (age1tag1...)  binds  the  secret
       to  one machine's TPM: nothing but that TPM can open it.  That is how a
       host being installed gets secrets it can use at first boot,  before  it
       has any GPG key.

       -seal  -backend  age -passphrase seals with a passphrase instead of re‐
       cipients (age -p, scrypt). This is the shape for a person's  own  iden‐
       tity keys: the ciphertext is safe in a private repository, opens on any
       host,  and is bound to no hardware. It is the one -seal form that reads
       a redirect on stdin, because a private key is a multi-line file, not  a
       line anyone types; what arrives must be an OpenSSH private key or a PGP
       private  key  block  unless  -any  says  otherwise.  age  asks  for the
       passphrase itself on the controlling terminal, so  a  terminal  is  re‐
       quired  even with stdin redirected. Seal key files as they are: a key's
       own passphrase stays as a second layer.

       -install-keys is the first-login half. It opens every passphrase-sealed
       .age file in -dir (age asks for the passphrase once per file), installs
       an OpenSSH key under ~/.ssh (0600, directory 0700) with  its  .pub  de‐
       rived by ssh-keygen -y, imports a PGP key block with gpg --import, cre‐
       ates  ~/.hee/secrets  (0700), and runs hee-trust anchor when ~/.hee/in‐
       dex/_.yaml is missing. One status line per item, never any  key  mater‐
       ial.  An  existing identical key is a no-op; a differing one is refused
       unless -force is given. Exit 0 when everything is OK, 1 with a WARNING,
       2 with a CRITICAL.

       -pass decrypts and sets the secret  in  the  HEE_CRED_PASS  environment
       variable  of the -exec child process only -- never argv (visible via ps
       to other users), never stdout, never a log line. The backend is  chosen
       by  which  file exists; an account with both a .gpg and an .age file is
       refused rather than guessed at.

       -github-app and -github-token give an organization's automation  GitHub
       access  without  a  personal  token.  A personal access token of either
       kind is tied to the person who made it; a GitHub App belongs to the or‐
       ganization. The App's private key is sealed here like any other creden‐
       tial, and everything that is not secret -- the organization, the  App's
       client  id,  its permission ceiling, the keys its private key is sealed
       to, and one grant per identity -- lives in  a  registry  (see  ENVIRON‐
       MENT).

       -github-app  walks  one App through its life. Not registered: it prints
       GitHub's registration link, pre-filled with the ceiling, private,  with
       no  webhook,  and exits 1. With -key, the private key file GitHub down‐
       loaded: it checks that the file is an RSA key that signs, and seals  it
       to  the registry's recipients. Registered and sealed: it opens the key,
       asks GitHub what the organization's installation  holds,  and  compares
       that with the ceiling -- more is CRITICAL, less is WARNING.

       -github-token  changes what -run or -pass hands the child: not the key,
       but one installation token for GRANT, in GH_TOKEN (or  -as  VAR).   The
       token  names  only  the grant's repositories -- a regular expression, a
       list, or the agent roster's scope.repos -- and a subset  of  the  App's
       permissions.  A  grant  above  the  ceiling is refused before GitHub is
       called; a token whose granted permissions or repositories  differ  from
       the request is revoked and refused. The child never sees HEE_CRED_PASS,
       and  the  token is revoked when the child exits, so it lives as long as
       the command and never longer than GitHub's one hour. The  child's  exit
       code is the tool's.

OPTIONS
       -seal ACCOUNT
              Seal a new secret under the given account name.

       -recipients ID[,ID...]
              Comma-separated  GPG key IDs or emails to encrypt to, or age re‐
              cipients with -backend age.  At least one required. Multiple re‐
              cipients means any one of them can independently decrypt.

       -backend gpg|age
              With -seal: the encryption backend (default  gpg).   age  writes
              ACCOUNT.age and needs age on PATH, plus age-plugin-tpm for a TPM
              recipient.  Refused  if  the account already has a file from the
              other backend.

       -passphrase
              With -seal -backend age: seal with a passphrase (scrypt) instead
              of -recipients, which is then refused. Reads a key file  from  a
              stdin redirect, or a typed line with -any.  Needs a terminal for
              age's own passphrase prompt.

       -any   With -passphrase: accept plaintext that is not an OpenSSH or PGP
              private key.

       -install-keys
              Open  every  passphrase-sealed  .age file in -dir and install it
              (see DESCRIPTION).

       -account NAME
              With -install-keys: only files named NAME-*.age, installed with‐
              out   the   prefix,   so   spencer-id_ed25519.age    lands    as
              ~/.ssh/id_ed25519.

       -force With  -install-keys:  replace  an existing key that differs from
              the sealed one. With -github-app -key: replace a sealed App  key
              (a rotation).

       -run ACCOUNT
              Like  -pass  , but also exports the secret under a variable name
              derived from ACCOUNT: non-alphanumerics become  underscores  and
              the whole name is upper-cased, so plex-token arrives as PLEX_TO‐
              KEN, cf-dns-token as CF_DNS_TOKEN.  This is the naming operators
              were  already applying by hand in every -exec wrapper, so a con‐
              sumer needs no sh -c shim to rename it.  HEE_CRED_PASS is  still
              set as well, so existing wrappers keep working.

       -as VAR
              With  -run or -pass: use VAR as the variable name instead of the
              derived one. For a tool whose expected variable does not  follow
              from the credential's own name.

       -pass ACCOUNT
              Decrypt the named account's secret for one -exec call.

       -identity FILE
              With  -pass or -run on an .age credential: the age identity file
              to decrypt with. Defaults to HEE_CRED_AGE_IDENTITY.  A TPM iden‐
              tity file holds a key wrapped by that TPM and is useless on  any
              other machine.

       -github-app ACCOUNT
              Register,  seal  or  check  the  GitHub App whose private key is
              sealed as ACCOUNT (see DESCRIPTION). Exit 0  OK,  1  WARNING,  2
              CRITICAL.

       -key FILE
              With -github-app: the private key file GitHub downloaded, sealed
              to  the  registry's  seal_recipients.  An existing sealed key is
              replaced only with -force: generate the new key in GitHub,  seal
              it,  check,  then delete the old key in GitHub. Delete the down‐
              loaded file once it is sealed.

       -github-token GRANT
              With -run or -pass on  a  GitHub  App  key:  give  the  child  a
              one-hour  installation  token  for GRANT instead of the key, re‐
              voked when the child exits.

       -registry FILE
              With -github-app or -github-token: the GitHub App registry.  De‐
              faults   to   HEE_GITHUB_APPS,   else   ~/git/fleet-ops/hee/reg‐
              istries/github-apps.registry.v1.yaml.

       -exec COMMAND [ARGS...]
              The command to run with HEE_CRED_PASS set. Required with  -pass.
              Everything  after  the  first  -exec  belongs  to COMMAND and is
              passed to it untouched: its own short flags  (-r,  -b,  -t)  are
              never read as hee cred options, and a --help there is COMMAND's.

       -genfrom TERM
              Generate  a  passphrase  from real corpus text matching TERM in‐
              stead of typing one.

       -blocks N
              Number of corpus-derived words to join (default 4).

       -dir PATH
              Secrets directory (default .hee/secrets, relative to cwd).  With
              -github-app  or  -github-token, the .hee/secrets beside the reg‐
              istry's repository, so both work from any directory.

       -root PATH
              Corpus root for -genfrom (default /var/local/hee-corpus).

       -reseal ACCOUNT|all
              With -add-recipients: open the sealed .gpg credential here,  re-
              encrypt  it  to  its existing recipients plus the added key ids,
              verify the new file opens to the same value, and replace the old
              one; a file this host cannot open is reported with  its  recipi‐
              ents and skipped.

              Without  -add-recipients: normalize the encoding. A .gpg that is
              binary OpenPGP (sealed by hand without --armor) is rewritten  as
              ASCII armor around the same ciphertext; nothing is decrypted and
              no key is needed. The armored form is checked with gpg --dearmor
              to  be  byte-identical  before it replaces the file. Exit 0 when
              every file is armored,  1  when  one  was  neither  armored  nor
              OpenPGP and was left alone, 2 on a mismatch (original kept).

       -add-recipients ID[,ID...]
              With  -reseal:  GPG  key ids or emails to add; their public keys
              must be in this keyring.

EXAMPLES
       Seal a secret, two recipients:

              hee cred -seal my-api-key \
                  -recipients 6A58FE47...3188,73B1462A...FDA0

       Use a sealed secret without ever seeing it:

              hee cred -pass my-api-key -exec bash -c \
                  'curl    -H    "Authorization:    Bearer     $HEE_CRED_PASS"
              https://api.example.com'

       Preferred pattern for a tool that reads its secret from stdin: seal it,
       then  pipe  it in from the -exec child, so the plaintext exists only on
       that one pipe and never on a command line, in a file, or in a log:

              hee cred -pass registry-login -exec sh -c \
                  'printf %s "$HEE_CRED_PASS" | docker login  -u  bot  --pass‐
              word-stdin'

       Seal  a  Wi-Fi password to this machine's TPM, then open it on the same
       machine (the identity comes from age-plugin-tpm --generate):

              hee cred -seal wifi -backend age \
                  -recipients   "$(age-plugin-tpm   -y   identity.txt)"   -dir
              .hee/secrets
              hee cred -run wifi -identity identity.txt -dir .hee/secrets \
                  -exec nmcli connection modify home wifi-sec.psk-flags 0 ...

       Seal  your  own  SSH  and GPG keys with a passphrase for a host that is
       about to be bootstrapped, then install them at its first login:

              hee cred -seal spencer-id_ed25519 -backend age -passphrase \
                  -dir hosts/flippy/keys < ~/.ssh/id_ed25519
              gpg --armor --export-secret-keys KEYID | \
                  hee cred -seal spencer-gpg  -backend  age  -passphrase  -dir
              hosts/flippy/keys
              # on the new host, as the account, at its first login
              hee cred -install-keys -dir ~/keys -account spencer

       Register the organization's GitHub App, seal its key, check it, and run
       one command with a token that dies when the command does:

              hee cred -github-app github-app-tcos-agents
              hee cred -github-app github-app-tcos-agents \
                  -key ~/Downloads/tcos-agents.2026-09-13.private-key.pem
              hee cred -run github-app-tcos-agents -github-token touchy-claude
              \
                  -exec gh pr list --repo Twin-Cities-Open-Systems/fleet-ops

SECURITY
       A  secret  sealed to multiple recipients can be decrypted independently
       by any one of them -- this is intentional, not a  weakness.  Add  every
       real  party that legitimately needs access as a recipient at seal time;
       there is no way to add a recipient after the fact without re-sealing.

       A TPM-sealed secret dies with that TPM: a firmware TPM clear or a board
       replacement makes it unrecoverable. Keep the plaintext's real source of
       truth (a password manager) and treat the sealed copy as a delivery  ve‐
       hicle, not a backup.

       A  passphrase-sealed  file is exactly as strong as its passphrase: keep
       that in the password manager, never in a repository or a chat, and seal
       key files with  their  own  passphrases  intact  so  a  leaked  sealing
       passphrase  still  yields locked keys. Once installed, the keys rest on
       the host's disk; an unencrypted root filesystem  is  then  the  weakest
       link, not this tool.

       A GitHub App private key does not expire. Whoever holds it can mint to‐
       kens up to the App's ceiling until an owner deletes that key in GitHub,
       so  keep the ceiling as small as the grants need, delete the downloaded
       file once it is sealed, and rotate by adding a new key before  deleting
       the old one (an App may hold up to 25).

ORGANIZATION
       Twin Cities Open Systems - Operations LLC
       IANA Private Enterprise Number: 1.3.6.1.4.1.66550

SEE ALSO
       hee-pwgen(1), hee-qr(1), age(1), gh(1)

ENVIRONMENT
       HEE_CRED_DIR
              Absolute  path to the secrets store, overriding the relative de‐
              fault .hee/secrets.  Set it in heerc to pin one  store  per  ma‐
              chine; -dir still wins when given.

       HEE_CRED_AGE_IDENTITY
              The  age identity file used to open .age credentials when -iden‐
              tity is not given.

       HEE_CRED_PASS
              Set in the child's environment by -pass and -run.

       HEE_CRED_TTY
              The  device  checked  for  age's  passphrase   prompt   (default
              /dev/tty).   For  the  test  suite,  whose  stand-in  age  never
              prompts; nothing else should set it.

       HEE_GITHUB_APPS
              The GitHub App registry, when -registry is not given.

       GH_TOKEN
              Set in the child's  environment  by  -github-token,  unless  -as
              names another variable.

       HEE_GITHUB_API
              The  GitHub REST API root (default https://api.github.com).  For
              the test suite's local stand-in; nothing else should set it.

HEE                               2026-09-13                       HEE-CRED(1)