keyfork/docs/src/usage.md

# Common Usage

Keyfork is a tool to help manage the creation and derivation of binary data
using [BIP-0039] mnemonics. A mnemonic is, in simple terms, a way of encoding a
random number between 128 and 256 bits large, as a list of 12 to 24 words that
can be easily stored or memorized. Once a user has a mnemonic, Keyfork utilizes
[BIP-0032] to derive cryptographic keys, which can be utilized by a variety of
applications.

Once a user has generated a mnemonic with [`keyfork mnemonic generate`], the
mnemonic can be loaded to [`keyforkd`]. This is typically done automatically by
[`keyfork`], but plumbing binaries (commands that are not `keyfork`, such as
`keyfork-derive-key`) require the server to be started manually.

**NOTE:** Anything beyond this point should be considered Design by
Documentation, and while the commands are not likely to change between now and
when they are released, there is no current stable interface for these
commands, and they may change at any time.

Users can then "provision" keys, or automatically deploy generated keys to
specific endpoints. Running `keyfork provision` will automatically list all
known provisioners, while running `keyfork provision help <provisioner>` will
include detailed information about the specific provisioner. For OpenPGP
smartcards (such as Yubikeys), `keyfork provision openpgp-card` will
automatically derive an OpenPGP key and provision it to a smartcard. As
previously mentioned, if `keyforkd` was not previously started, a prompt will
be provided by the provisioner for the mnemonic, and `keyforkd` will be started
in the background.

Any usage of `keyfork provision` or `keyfork derive` can also be given the
`--save` flag, to modify a `keyfork.toml` file and record when the key was
derived, and for what purpose. This is useful, for instance, with OpenPGP,
where a key may be derived with certain capabilities that may not be remembered
otherwise. Later, the command `keyfork recover` can be used to automatically
re-provision each previously invoked provisioner, and re-derive all previously
invoked derivation, through an interactive prompt.

[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
[`keyfork mnemonic generate`]: ./bin/keyfork/mnemonic/index.md#generate
[`keyforkd`]: ./bin/keyforkd.md
[`keyfork`]: ./bin/keyfork.md