fcli

Credentials

f creds stores credentials encrypted at rest in ~/.f/f.creds.enc (mode 0600). The key is derived from a passkey you choose (scrypt KDF) and values are encrypted with AES-256-GCM.

f creds unlock [passkey] [--ttl <dur>]  # start daemon (default 10m; s/m/h/d/w)
f creds set prod.db "postgres://u:p@h" # store
f creds get prod.db --secrets          # print — redacted without --secrets
f creds ls                             # list names (provider mirrors hidden)
f creds rm prod.db                     # remove
f creds status                         # locked / unlocked + time left, + provider readiness
f creds forget [name…]                 # drop provider mirror(s) + the miss cache
f creds request <name> [--timeout sec] # block until the cred is set elsewhere
f creds waiters                        # list open waiting requests
f creds fill [name]                    # prompt + set values for open waiters
f creds files <sub>                    # whole files in the same box
f creds lock                           # stop daemon, zeroize key

Durations (--ttl, --timeout) are a plain number of seconds or a length with s/m/h/d/w units: 900, 45m, 2h, 1d, 1d6h30m.

How it works

  • Unlock spawns a background daemon that derives the key once and holds it in memory — the passkey never touches disk and there is no key file. The daemon serves ops over a unix socket (~/.f/.creds.sock) and auto-exits after the TTL (default 10 min), zeroizing the key.
  • Wrong passkey fails loudly: AES-GCM authentication rejects the data ("unable to authenticate data") rather than returning garbled plaintext.
  • Lock (or TTL expiry) kills the daemon and removes the socket; the encrypted store on disk is untouched.

Reading and writing values

f creds get redacts by default. Without --secrets the value is not printed, only [redacted — pass --secrets to reveal], so a get in a log, a transcript or an agent trace leaks nothing. request is the same: it confirms the cred arrived and stays silent unless you pass --secrets.

f creds get prod.db                 # [redacted — pass --secrets to reveal]
f creds get prod.db --secrets       # postgres://u:p@h
f creds get prod.db --source        # value + `f: source: local:prod.db` on stderr

set prefers a pipe over argv: with no value argument (or with -) it reads stdin, and on a terminal it prompts without echoing. Passing a secret as a word on the command line works, and f says so — anything in argv is readable from ps for the life of the process:

echo SECRET | f creds set prod.db   # prints: set  prod.db  (stdin)
f creds set prod.db                 # terminal: prompts without echo
f creds set prod.db 'postgres://…'  # works, with a note about `ps`

Names are opaque strings. Two prefixes are reserved: mirror: (provider mirrors, below) and file: (packed files, below). f creds set 'mirror:x' v is refused — mirrors belong to their provider, not to you.

Provider fall-through

f creds get reads the local box first. On a miss it asks every registered credential provider — see Providers — and mirrors a hit into the box as mirror:<name> under a TTL, so later reads are offline, fast, and survive the provider being unreachable.

f creds get github.com --secrets --source
# s3cret
# f: source: myprov:github.com (mirrored)     ← the provider answered, not the box

f creds ls                     # (1 provider mirror(s) hidden — --all)
f creds ls --all               # mirror:github.com  (mirror; myprov; expires 2026-10-17T04:50:08.805Z)
f creds forget github.com      # drop that mirror + its cached miss; no args = all mirrors

Because a mirror is a real copy of a secret, f creds rm mirror:<name> is a real deletion. f creds rm <name> where only a mirror exists drops the local copy and tells you the provider still answers for that name — the next get re-mirrors it. To stop a name resolving, remove it at the source.

Flags on get

flag meaning
--secrets print the value; without it the output is redacted
--local box only: never consult providers, and a local miss exits 1
--vault skip the local value and the mirror, revalidate with the provider now
--source print provenance to stderr (local:<name>, <provider>:<name> (mirrored))
--no-cache ignore and clear the negative cache for that name first

--local restricts the command to the box on your machine. Neither get nor lookup consults a provider, and neither serves a mirror:<name> entry: a miss is reported as a miss, with exit 1.

f creds get <name> --local      # box only — f: no such cred: <name> if it is not here
f creds lookup <name> --local   # same rule, machine-facing output

Use it to tell a real local secret apart from a provider mirror. --source still works alongside it, and a local hit reports f: source: local:<name>.

The miss cache

A name no provider knows is cached briefly (300s) so one typo does not hammer a server on every invocation. --no-cache resets one name; f creds forget clears them. The cache lives in ~/.f/.creds-cache.json (plaintext at rest, mode 0600) as miss:<name> entries, next to src:<name> provenance — those are not box keys, so f creds ls never shows them and f creds rm cannot clear them.

Providers are configured in ~/.f/f.config.json:

{
  "providers": { "myprov": { "mirrorTtlSec": 3600, "enabled": false } },
  "mirrorTtlSec": 3600
}

enabled: false takes a provider out of the ladder without uninstalling its uck; mirrorTtlSec bounds how long a mirrored hit may go before it is revalidated.

Providers

A credential provider is any uck that exports a credentialProvider object alongside register(). f providers lists them and their readiness; f creds status prints the same readiness lines.

f providers            # one row per provider: myprov  uck:myprov  mirrorTtl:3600s
f providers --dump     # the discovery payload `f creds` actually reads (--json is the same)

On a fresh install there are none — no default uck is a provider — and the output says so with exit code 0.

The interface, normative in section 5 of CONTRACT.md in the fcli-ucks repo:

credentialProvider: {
  name: "myprov",            // required; the id in provenance and status output
  resolve: (name) => value,  // required
  has?: (name) => boolean,   // optional pre-filter
  status?: () => ({ ready, note?, hint? }),
  mirrorTtlSec?: number,     // floor on how long a hit may go un-revalidated
}

resolve(name) has exactly three outcomes, and the difference is the whole contract:

outcome meaning what you see
a value (string or Buffer) a hit the value, mirrored as mirror:<name>
null / undefined / "" "this name is not mine" the next provider, then no such cred: <name>
throws availability failure the error, verbatim, exit non-zero

Returning null for a failure is the cardinal sin: an unreachable vault reads as "you have no such credential". Throwing is how a provider says broken rather than absent — verified against a provider that throws:

f: provider 'myprov' failed: … myprov is offline     # exit 1

has(name) is a trap. If it answers false, resolve is never called and that answer is cached. Implement it only if it can answer offline; not implementing it is always safe. status() feeds f creds status and f providers — report readiness, not ownership.

Discovery imports every installed uck and reads the module-level credentialProvider export — putting it on the object returned by register() is not enough, and nothing provider-owned runs until a name is looked up. For a provider whose index.js is also its CLI entry, creds reaches it as a child process (node <uck>/index.js resolve <name> | has <name> | status), so a provider must be side-effect free at module scope, must never prompt (throw instead), and must pass F_CREDS_NO_PROVIDER=1 through when it shells out to f — that is the recursion guard. Because the probe is a child process, a provider may not import a sibling bucket's shared code; dependencies belong in its own package.json.

Packed files

f creds files stores whole files in the same encrypted box, keyed by absolute path (file:<abs path>), with the manifest itself a normal cred entry named files. f creds pack and f creds unpack are aliases for f creds files pack / f creds files unpack.

f creds files pack ./id_ed25519 ./kubeconfig.yaml   # store, keyed by absolute path
f creds files ls                                    # path, bytes, mode, packed-at
f creds files ls --json                             # the raw manifest
f creds files unpack ./id_ed25519                   # restore in place (refuses an existing file)
f creds files unpack ./id_ed25519 --force           # … overwriting, with a .bak written first
f creds files unpack ./id_ed25519 --dir /tmp/stage  # stage under a root instead
f creds files unpack 'file:/root/.ssh/id_ed25519' - # raw bytes to stdout
f creds files unpack id_key '=>' /elsewhere/key     # restore to a different path
f creds files rm ./kubeconfig.yaml                  # drop one entry + its manifest line

Crossing terminals

request, waiters and fill exist because a uck often needs a credential the current session does not have — a token for a Forgejo instance, a registry password. Rather than fail, the uck blocks:

Terminal A — a uck (or you) needs a cred it does not have:

f creds get my.forge.example.com      # not set yet
f creds request my.forge.example.com  # blocks until someone sets it (default 300s)

Terminal B — the human, seeing what is outstanding:

f creds waiters                      # name + who is waiting
f creds fill                         # prompt for each open request

Terminal A unblocks as soon as the value is set.

request also waits for unlock if the daemon is merely locked, so a uck can ask for a secret and a TTL in one call without knowing the passkey. Waiters register themselves in ~/.f/.creds-waiters.json, which is what makes them visible from another terminal.

  • Other ucks can drive it via the exported credsApi (get / set / ls / unlock / lock / status / wait), which takes the same names — so a uck that needs a token can block on it the same way f creds request does.

Where these rules come from

CONTRACT.md in the fcli-ucks repo, section 5, is the normative text for the provider interface; creds/README.md in the same repo is the operational doc that mirrors it. Where they disagree this page follows CONTRACT.md and the built binary — and they do disagree: the README calls the store ~/.f/.creds.box and a files list subcommand, while creds/index.js writes ~/.f/f.creds.enc and the subcommand is files ls, and the README lists import/export commands this build's f creds usage does not offer.

Documentation for f. This page is built by the site generator.

site source