Quick start¶

All you need is Docker with Compose. The server runs in a container, and the bbk CLI runs from the same image, so there's nothing to compile.

1. Get the code and create its secrets (one time; on Windows, run this step in Git Bash or WSL):

git clone https://github.com/brian-summers/blackbook
cd blackbook

# The master keyfile: this one 32-byte file ultimately protects everything.
# It's mounted as a Docker secret and kept OFF the data volume, so a copy of
# the volume alone can't decrypt anything. Back it up somewhere safe and
# separate. If you lose it, the data is gone.
mkdir secrets
openssl rand -out secrets/master_keyfile 32

# TLS certificates for the server-to-database link.
./scripts/generate-postgres-certs.sh

# Database passwords: copy the template, then change every value in .env.
cp .env.example .env

2. Start the server:

docker compose up -d

3. Install the bbk command. It's a small script that runs the CLI from the image you just built. It finds the local server on its own and keeps your saved logins in a Docker volume.

# Linux, macOS, WSL, Git Bash (make sure ~/.local/bin is on your PATH)
mkdir -p ~/.local/bin && install -m 755 scripts/bbk ~/.local/bin/

# Windows PowerShell: any folder on your PATH works; this creates one
New-Item -ItemType Directory -Force "$HOME\bin" | Out-Null
Copy-Item scripts\bbk.ps1, scripts\bbk.cmd "$HOME\bin"
[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path', 'User'));$HOME\bin", 'User')

Then open a new terminal. Prefer a native binary? cargo install --path . builds one instead (on Windows it also needs perl, for the bundled OpenSSL), and every step below is the same.

4. Log in. On first start the server writes an admin "bundle" (server address, token, certificate, key, and CA) to its volume. It's the only place the admin token ever appears; it's never logged. Copy it out, log in, and delete the copy:

docker cp blackbook-app:/opt/blackbook/data/admin-bundle.json .
bbk login admin-bundle.json
rm admin-bundle.json

You're ready:

bbk put api-key sk_live_super_secret   # save a secret
bbk get api-key                         # read it back
bbk ls                                  # list what you have

A note on the login passphrase. Blackbook encrypts your saved credentials on your disk, so login asks you to choose a passphrase to seal them. So you're not prompted on every command, bbk unlock caches the derived key for a while (default 15 minutes); bbk lock clears it. For scripts, set $BLACKBOOK_PASSPHRASE.