YB-FORMAT(1)

🌸 YB-FORMAT(1) — the format girlies' era begins 🌸

okay so real talk, this is the format page from the yb manual fam — section 1, User Commands, bestie. sit down, grab a strawberry drink 🍓, and let's get your YubiKey ready.

✨ NAME ✨

format — provisions PIV objects and, if you want, generates an ECDH key too 💅

🎀 SYNOPSIS 🎀

format [-c|--object-count] [-k|--key-slot] [-g|--generate]
[-n|--subject] [--protect] [--yes] [--plan] [-h|--help]

🦋 DESCRIPTION 🦋

So like, format is the glow-up your YubiKey needs before it can hang out with yb(1). It writes a brand-new store header and allocates COUNT PIV data objects. Heads up though: any existing yb data on the card gets erased, no cap, gone, bye 🙈. Each object is written at exactly the size its content needs — 9-byte sentinel for empty slots, up to 3,063 bytes for occupied ones. Efficient queen behavior 👑

---

If you run format from a terminal with no format options at all, you get the guided experience and honestly? it's giving personal assistant. It shows you the state of the YubiKey (literally exactly like yb fsck does), changes a factory-default PIN and PUK, keeps or replaces the key in slot 0x82, always keeps the management key on the YubiKey (unlocked by the PIN, so that writes need only the PIN), shows you the plan, and asks for confirmation before writing anything. And when the plan is about to destroy blobs or an existing key? The confirmation is the YubiKey's serial number. Like, type the serial, prove you mean it 🫶.

Any format option — or --yes — switches you to the flag-driven mode described below, and so does running without a terminal. yb format --yes formats with the defaults, no prompting, out the door 💨.

By default, format expects an ECDH key to already exist in the chosen PIV slot, and it checks that it matches the slot's X.509 certificate. Want a fresh one? Pass --generate and it creates a new P-256 key pair plus a self-signed certificate, right on the card ✨.

---

Pass --protect to keep the management key on the YubiKey, unlocked by the PIN. If it's not kept there, it gets replaced with a random key stored in the PRINTED PIV object — which only the PIN unlocks. If it already is kept there, it stays. This is such a convenience: you no longer need to keep the management key yourself 😭. After this, future write operations only require the PIN — no YB_MANAGEMENT_KEY or --key needed, periodt. The current management key is taken from YB_MANAGEMENT_KEY / --key, else from PRINTED if the card is already protected, else the factory default.

Pass --plan to run the checks and print the plan without writing anything. Important vibe check: --plan does talk to the YubiKey and verifies the PIN — and it exits with status 1, with the error the real command would give, when a check fails. It's a dress rehearsal, not a fake one 💀.

Here's the order of operations, because the order is iconic: format first checks everything it can without writing (PIN, management key, slot key) and lists the blobs it's gonna destroy. Then it sets up protection, erases the store, and generates the key last — so a failure never leaves blobs behind a replaced key. If it stops partway through, the message tells you what was done and what to run next. Thoughtful and communicative, we love to see it 🌈.

🚨 real one: format must be run once before store, fetch, or any other command that accesses the store. no format, no store. that's the rule.

💖 OPTIONS 💖

• -c, --object-count <OBJECT_COUNT> — how many PIV objects to allocate (1–32) [default: 32]
• -k, --key-slot <KEY_SLOT> — PIV slot for the ECDH encryption key (decimal or 0x-prefixed hex) [default: 0x82]
• -g, --generate — generate a new EC key pair in the chosen slot ✨
• -n, --subject <SUBJECT> — X.509 subject for the self-signed certificate (only with --generate) [default: /CN=YBLOB ECCP256]
• --protect — keep the management key on the YubiKey, unlocked by the PIN.

If it's not kept there, replace it with a random key stored in the PRINTED object, which only the PIN unlocks, so that future write operations only require the PIN. If it already is, keep it. The current management key is taken from YB_MANAGEMENT_KEY, else from PRINTED if the YubiKey is already protected, else the factory default.

• --yes — format without the guided flow, even from a terminal: keep the key in the slot, 32 objects, no protection (unless other flags say otherwise)
• --plan — run the checks and show what the format would do, then stop.

Talks to the YubiKey (and verifies the PIN) but writes nothing. 🫶

• -h, --help — print help (see a summary with -h)

🌟 EXAMPLES 🌟

First-time setup, guided:

yb format

First-time setup from a script — generate a key, format, and keep the management key on the YubiKey:

yb format --generate --protect

Show what that would do, without writing anything:

yb format --generate --protect --plan

First-time setup, keeping the management key yourself:

yb format --generate

Compact store (10 objects) in slot 0x83:

yb format -c 10 -k 0x83 --generate

Re-format using an existing key in slot 0x9D:

yb format -k 0x9D

👑 SEE ALSO 👑

yb(1), yb-store(1), yb-fsck(1), ykman(1) — go read the whole fam, iykyk 💜

---

that's the whole page bestie, go format something gorgeous 🔥 — this was yb, 2026-03, page YB-FORMAT(1) (section 1, User Commands), signing off with a 🎀 and a 💅 fr fr