CLI

Who this is for: whoever runs the deployment. If you are integrating an application rather than operating a server, you want the API reference and an SDK — the CLI is not on that path. New here? Quickstart uses about six of these commands and explains them in order.

Getting the CLI#

The CLI ships as a container image, so there is nothing to install and nothing to keep up to date by hand. Alias it once and every command below runs inside it:

# the alias mounts your working directory, the Docker socket the CLI drives, and
# ~/.config/ydentifi, where the API key from `ydfi register` is kept
$ mkdir -p ~/.config/ydentifi && chmod 700 ~/.config/ydentifi
$ alias ydfi='docker run --rm -it -v "$PWD":/work \
      -v "$HOME/.config/ydentifi":/config/ydentifi -e XDG_CONFIG_HOME=/config \
      -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/ydentifi/ydfi'
$ ydfi --version

Three flags work everywhere. --help on any command or group prints its own tree and flags — that output is generated from the same definitions as this page, so it is never out of date. --version prints the build, which is stamped in at release time. --no-color strips ANSI codes, as does setting NO_COLOR in the environment, which is what you want in CI logs.

The twelve groups#

Every command is ydfi <group> <command>. The groups split by what you are operating on, not by how often you touch them — so the ones you use once at install sit beside the ones you use weekly.

Every command#

ydfi bootstrap

The shortest path from nothing to a deployment that can start. Writes the PKI, generates every secret, and emits a .env wired to both.

ydfi deploy

Recipes, not a framework. local is a real Docker Compose deployment on your machine — the same server image production runs, with the same mutual-TLS handshake.

ydfi pki

Readings of a certificate. It issues nothing: ydfi bootstrap makes a new deployment’s certificates, and your own CA issues under that root after.

ydfi secret

The deployment’s own key material. To encrypt new data under a new key, append the generated pair to YDFI_PRIMARY_ENCRYPTION_KEY and restart; the older pairs stay and decrypt what they wrote. With more than one server instance, add it first in the list, where it only decrypts, restart every instance, then move it to the end and restart again.

Licensing account

register exchanges a code sent to your address for an API key, kept on this machine. pull downloads the license the account is entitled to. See Get a license.

ydfi license

Inspecting and installing the license. ydfi pull downloads one; apply installs it at the path the server reads.

ydfi deployment

A license file, checked locally; each command takes --license-file. preview-license is the one to know: it answers what would this license do given the users and seats I already have before you install it.

ydfi admin

Everything against a running server, over mutual TLS. This is the largest group and the only one that writes to production data, so it is also the one with the strictest conventions — see below.

ydfi invite

One command, because enrollment only needs one. The token it prints is what a QR code carries.

ydfi seed

A demo relying party you can point a phone at without writing any integration code first. Useful for evaluation and for reproducing a report against something known.

ydfi validate-env

Reads a .env and tells you what is wrong with it before anything tries to boot on it.

Conventions that repeat#

The same handful of flags recur across the whole tree, and they mean the same thing everywhere. Learn these five and most of the CLI stops needing its own documentation.

Exit behavior

Success exits 0. Any failure exits 1 with the error on stderr and nothing useful on stdout — so if ydfi ...; then and piping stdout to a parser both behave. Errors carry the server’s typed reason where there is one; see Errors.