Skip to content

Core concepts

Four ideas cover almost everything you'll do.

1. Secrets and files

A secret is a short string (a key, a password, a token). A file is any file up to 64 MiB (a certificate, a keystore, a config blob). They behave the same way and support the same protections — you just use put/get for secrets and file put/file get for files.

bbk put db-password "hunter2"
bbk file put ./service-account.json --name gcp-sa

2. Identities (profiles)

Each person or app that uses Blackbook is a client with its own identity. On your machine, a saved, encrypted login is called a profile (stored under ~/.bbk). You can hold several at once and pick one per command with -P:

bbk -P alice get api-key      # act as alice
bbk -P bob   get api-key      # act as bob, same shell
bbk profile ls                # '*' marks your default

An admin provisions a new client and hands them a bundle to log in with:

bbk client create alice --out alice.json   # admin does this
bbk login alice.json                        # alice does this

3. Domains (your private space + shared spaces)

A domain is a named space that is both a folder and a group. Two ideas, one word:

  • The same name (say, api-key) can live in different domains without colliding.
  • Granting permission to a domain (written @engineering) grants it to every member of that domain.

Every client automatically gets a private domain of its own, named ~yourname, that only they administer — no admin has to set anything up. When you log in, that private space becomes your default, so bbk put api-key ... just works and lands somewhere only you can reach.

bbk whoami                    # shows e.g. "user domain: ~alice"
bbk put api-key sk_xxx        # lands in ~alice, no setup needed
bbk -D engineering get k      # reach into a shared domain when you need to

4. Permissions (ACLs)

By default you can reach your own private domain and nothing else. To share, an admin (or a domain admin) grants a permission rule: a subject, a name pattern, and which actions are allowed.

# Everyone in @engineering may read and update anything named prod-*
bbk acl grant "@engineering" "prod-*" --read --update --domain engineering

# Give alice read access to one path, but only 5 times and only until year-end
bbk acl grant alice "rotated-keys/*" --read --max-uses 5 --expires-at 2026-12-31T00:00:00Z

Rules can be scoped to a single client or a whole group, limited to a time window (--not-before / --expires-at), and capped to a number of uses (--max-uses) that counts down and then stops authorizing — automatically.

Here's how those pieces relate:

flowchart LR
    alice["alice"]
    bob["bob"]
    priv["~alice<br/>alice's private space"]
    eng["engineering<br/>shared domain / group"]
    items["prod-* secrets and files"]

    alice --- priv
    alice --- eng
    bob --- eng
    eng -->|"permission: read + update prod-*"| items