Reference

CLI

livybolt is the primary way to use Livybolt. It generates and holds your keys locally, pays Lightning invoices in two phases, and decrypts responses on your machine. The server never sees a private key.

Install

npm i -g livybolt
livybolt --help

Every command talks to https://livybolt.com by default. Override it with --host on any command, or the LIVYBOLT_HOST environment variable.

The whole loop

livybolt id new --password "correct horse battery staple"
livybolt create survey.json                        # → invoice + handle
#   ...pay the invoice...
livybolt create --resume <handle> --preimage <hex> # → public URL + vaulted
livybolt balance --survey <id>                     # watch the pool fill
livybolt vault read --survey <id>                  # decrypt responses locally
livybolt unlock --survey <id> --count 25           # got more than you prepaid?
livybolt unlock --resume <handle> --preimage <hex> # pay to read the overage

Everything below is the reference for those commands.

Concepts

• Seed — one BIP-39 mnemonic from livybolt id new, stored at ~/.livybolt/identity.json. Everything derives from it: the identity key at account 0, each per-survey key at the next index. The 12 words are the single backup.
• Identity key — account 0. Locks your vault at rest; never sent to the server, encrypts no responses.
• Per-survey key — derived at a fresh index by livybolt create. Its public half is the survey's encryption_pubkey (answers are sealed to it); its private half decrypts responses and signs your reads. Derived, so never stored — it re-derives from the seed on demand.
• Vault — ~/.livybolt/vault.jsonl, sealed to your identity. Per survey it holds only the id and key index — no secrets. Lose it and livybolt vault rebuild reconstructs it from the seed.

livybolt id

Manage your self-custody identity. All operations are local.

livybolt create

Two-phase, because you pay the invoice out of band. Phase 1 derives the next per-survey key pair from your seed — the encryption key and its dashboard view key, at the same index — sends only their public halves, and returns an invoice + a short handle. Phase 2 mints the survey after you pay.

# phase 1 — describe the survey, get an invoice
livybolt create survey.json
#   handle:  9f3a2b1c0d
#   total:   5100 sats
#   invoice: lnbc...

# pay the invoice with any Lightning wallet, then:

# phase 2 — mint after paying
livybolt create --resume 9f3a2b1c0d --preimage <preimage-hex>
#   survey created ✔
#   public:    https://livybolt.com/s/<slug>
#   Sealed into your vault.

Phase 2 seals the new survey's id and key index into your vault, so a later livybolt vault read can re-derive the decrypt key and open the responses — you never handle keys by hand.

survey.json

{
  "title": "Launch feedback",
  "expected_responses": 100,
  "per_response_sats": 50,
  "questions": [
    { "id": "q1", "text": "How did you hear about us?", "type": "short_text" },
    { "id": "q2", "text": "How likely are you to recommend us?", "type": "rating" },
    { "id": "q3", "text": "Any other thoughts?", "type": "open_ended", "required": false }
  ]
}

Question type is one of: multiple_choice, multiple_select, open_ended, short_text, rating, yes_no. Choice types take an options array.

What you pay

total = create_fee + (expected_responses × per_response_sats)
      = 100      + (100 × 50)
      = 5,100 sats, paid once, up front

livybolt balance

Prepaid-pool accounting for a survey. Owner-gated, no payment.

livybolt balance --survey <id>
#   prepaid:   100
#   consumed:  40
#   remaining: 60  (3000 sats of credit)
#   locked:    0   (overage awaiting unlock)

livybolt balance --survey <id> --json   # machine-readable

livybolt unlock

Responses beyond the prepaid pool are stored locked. Unlocking pays an L402 invoice to promote the N oldest locked responses (FIFO). Two-phase, like create.

# phase 1 — invoice to unlock 10 overage responses
livybolt unlock --survey <id> --count 10
#   handle:  4c5d6e...
#   total:   750 sats
#   invoice: lnbc...

# pay, then:

# phase 2 — unlock after paying
livybolt unlock --resume 4c5d6e... --preimage <preimage-hex>
#   unlocked 10 responses ✔

livybolt vault read --survey <id>   # they now appear

Both phases authenticate with NIP-98 signed by the survey key, so each asks for your identity password — phase 2 signs a fresh proof at resume time (the phase-1 signature expires while you pay), and the pending file never holds key material.

livybolt vault

vault rebuild is the payoff of derived keys: your 12 seed words restore not just the identity but the full list of surveys and their decrypt keys, with no server-side account and nothing else to back up.

livybolt pair

Provision the browser dashboard with your view seed — the read-only hierarchy derived one-way from your master seed. The CLI asks for a new pairing password (it must differ from your identity password), then prints a QR code and a copyable ncryptsec1… string — the same encrypted blob in two encodings. Scan or paste it on the dashboard and enter the pairing password once; the browser re-wraps the view seed under Face ID / Touch ID / PIN.

livybolt pair            # QR + pairing string
livybolt pair --no-qr    # string only

The blob is durable and reusable — keep it in a password manager to pair future browsers without this machine. It grants read access only; your master seed and identity never leave the CLI.

Environment & files