Command reference¶
Three flags are global — valid on any subcommand, before or after it:
| Global | Short | What it does |
|---|---|---|
--profile NAME |
-P |
Which saved identity to act as. Overrides $BLACKBOOK_PROFILE and the active profile. |
--domain NAME |
-D |
Target a non-default domain. Precedence: -D → $BLACKBOOK_DOMAIN → your saved domain use → default. |
--mfa CODE |
-m |
Send a two-factor code with the request. |
| Command | What it does |
|---|---|
login BUNDLE [-s SERVER] |
Log in from a bundle file (- reads it from stdin) and save an encrypted profile named after your identity. -s overrides the server URL. |
logout / whoami |
Forget the active profile / show your identity and private domain. |
unlock [-t MIN] / lock |
Cache your unlock key for -t minutes (default 15) so you aren't re-prompted / clear it. |
passphrase |
Change the passphrase that encrypts your saved profile. |
profile ls / use NAME / show / rm NAME |
List (active marked *) / switch default / inspect / delete a profile. |
put NAME VALUE [flags] |
Store a secret. Read-only by default (-o to overwrite, -i to make immutable). Protection flags below. |
get NAME [-r ID] [-w] [--external-passphrase P] |
Read a secret. -r supplies an approval request id; -w blocks until approved. |
ls / rm NAME |
List (shows KIND, STATUS, and a RULES summary) / delete secrets. |
rekey NAME [...] |
Change the client-side key on an external secret without changing its value. |
file put PATH [-n NAME] [flags] |
Upload a file (max 64 MiB). Same protection flags as put, plus client-side options. |
file get NAME [PATH] [...] / file ls / file rm NAME / file rotate NAME |
Download / list / delete / rotate a file's encryption key. |
file rekey NAME [...] |
Change the client-side key on an external or resident file. |
client create NAME [-r role] [-t days] [-o PATH] |
Admin. Provision a client; it auto-joins default and gets its own ~NAME domain. |
client rotate NAME / client ls / client revoke NAME |
Admin. Reissue credentials / list / revoke a client. |
domain create NAME |
Admin. Create a domain (a namespace and a group). |
domain use [NAME] [--clear] |
Set/show/clear your default domain (self-service, no admin needed). |
domain ls / members NAME |
List domains / a domain's members. |
domain add-member D C [-r role] / rm-member D C |
Admin or domain-admin. Manage a domain's members. |
acl grant SUBJECT PATTERN [action flags] [bounds] |
Admin or domain-admin. Grant permission. @name = group. |
acl ls / acl revoke ID |
List / revoke permission rules. |
mfa enroll / mfa verify CODE |
Set up two-factor for yourself. |
approve REQUEST_ID |
Approve someone's K-of-N request. |
requests [ID] [-v] |
See requests you can act on — who can approve and who already has. |
grants add GRANTEE PATTERN [...] / grants ls / grants rm ID |
Pre-authorize a reader for a category of secrets / list / revoke. |
audit [-n N] / audit -v / audit --archive [...] |
Admin. View the log / verify the tamper-evidence chain / archive old entries. |
cleanup |
Admin. Purge self-destructed (tombstoned) secrets and files in the current domain. |
web [-b ADDR] |
Launch the local web console (default 127.0.0.1:8088). |
tunnel forward PEER ... / tunnel accept ... / tunnel ls |
Open / accept / list end-to-end-encrypted tunnels. |
key create NAME [-t TYPE] [-M] [--import PATH] |
Create a managed key (aes256-gcm, ed25519, or hmac) in the current domain, or import your own. |
key ls / key show NAME / key jwks NAME |
List keys / show versions and public key / print an Ed25519 key's JWK Set. |
key rotate NAME / key rm NAME |
Add a new key version (old ones keep working) / destroy a key and every version. |
crypto encrypt / crypto decrypt [FILE] [KEY] [--aad A] [-o OUT] |
Encrypt / decrypt with -k NAME, --cmk, --key-file PATH, or -p (passphrase). |
crypto sign / crypto verify -s SIG [FILE] [KEY] |
Ed25519 signatures and HMAC checks; verify also takes --public-key. |
crypto hash [FILE] [-a ALG] [KEY] |
SHA3 / SHA-2 digest, or an HMAC when a key is given. |
crypto token issue [KEY] [--sub/--aud/--iss] [--ttl] [-c K=V] / crypto token verify TOKEN [KEY] |
Issue / verify signed JWTs (EdDSA or HS256). |
crypto keygen -t TYPE -o PATH / crypto datakey -k NAME |
Make a local key file / get a data key for your own envelope encryption. |
crypto random / derive-key / password-hash / password-verify HASH / fingerprint |
Secure random bytes / passphrase KDFs / Argon2id password hashes / visual fingerprints. |
server [-b ADDR] / health |
Run the server / ping the database. |
rekey-dek |
Admin/operator. Rotate the master data-encryption key in one command. |
Store-time protection flags (for put and file put): -o/--overwrite, -i/--no-overwrite, -M/--mfa-required, -d/--delete-on-read, --max-reads N, -r/--rotate-on-read, -p/--preserve-on-cleanup, -q/--quorum K -s/--signatories a,b,c, and the client-side options -e/--external-key, --external-passphrase P, -E/--external-data (files), --external.