Developer workflow

BetterSign™

A developer-oriented command flow for installing BetterSign, starting the daemon, creating identities, writing plog state, tracking VLADs, and testing encrypted messages.

Stable identity

A VLAD remains stable while its keys and protected metadata rotate.

Self-verifying history

Every state transition is hash-linked and authorized by the previous log state.

Decentralized discovery

VLADemlia helps peers locate current records without becoming the trust root.

Routine rotation

Key changes become signed updates that followers can verify and apply.

Developer workflow

How To Use

Install the Tools

Install BetterSign with the platform installer, then confirm the CLI and server binaries are available. The bs CLI talks to the running daemon over the local Unix Domain Socket API.

Use --format json when scripting commands or feeding output into another tool.

curl --proto '=https' --tlsv1.2 -sSf https://sh.bettersign.io/install.sh | shbs --helpbs --versionbs --format json peer status

Start the Service

Start bs-server on machines that should own identities, follow VLADs, publish plog updates, serve peer requests, or update local integration points.

The daemon loads config, initializes or loads its identity, starts enabled subsystems, opens the local API socket, and begins tracking configured VLADs.

bs-server startbs peer statusbs peer bootstrap --timeout 30bs configbs config --path

Create an Identity

Create a new identity plog with bs new. The VLAD is the stable identifier; current keys, metadata, and subsystem state live inside the verified provenance log.

For automation, pass the name, description, template, and algorithms explicitly instead of using the interactive wizard.

bs newbs new --name alice --description "Alice developer identity"bs new --name service-api --template default --primary-algorithm ed25519 --recovery-algorithm ed25519 --encrypt-algorithm x25519bs logs listbs logs info <LOG_ID>bs get <LOG_ID> --path /keys/primary --format json

Manage Keys

The daemon keystore handles key generation, import, export, file signing, verification, encryption, and threshold recovery helpers.

Use named keys for scripts so later plog updates can refer to readable key IDs.

bs keys listbs keys generate --algorithm ed25519 --name primary-signingbs keys generate --algorithm x25519 --name inbox-encryptionbs keys export primary-signingbs keys import-file ./primary-signing.multikey --name restored-primarybs keys sign-file primary-signing ./release.tar.gz --combinedbs keys verify-file ./release.tar.gz.sig --original ./release.tar.gzbs keys split primary-signing --threshold 2 --limit 3 --out-dir ./shares --format jsonbs keys combine ./shares/primary-signing.share-0.json ./shares/primary-signing.share-1.json --import

Write Plog State

Use bs logs append to write signed state changes. The current authorized signing key signs the new entry, and followers verify the log before applying the derived state.

Rotating a public key is just another plog write: append the new key material at the relevant path and let tracking peers sync the new head.

bs logs append <LOG_ID> --signing-key primary-signing --path /data/name --value "Alice"bs logs append <LOG_ID> --signing-key primary-signing --path /data/ssh/sign --key-id new-ssh-keybs logs entries <LOG_ID>bs logs verify <LOG_ID>bs export <LOG_ID> --output ./identity.plog

Track VLADs on Servers

Servers follow VLADs they trust and apply verified state to local systems such as SSH access, TLS material, WireGuard metadata, or audit rules.

The top-level follow commands are shortcuts for the admin tracking configuration.

bs follow <VLAD_HEX>bs followingbs unfollow <VLAD_HEX>bs admin tracking add-vlad <VLAD_HEX>bs admin tracking list-vladsbs admin config get tracking.vlads

Integrate Services

Use bs admin to connect verified VLAD state to local service configuration. These commands operate through the local daemon, or through authorized remote administration when configured.

Start with list commands to confirm the current state before mutating server config.

bs admin ssh add-user --authorized-keys-path /home/alice/.ssh/authorized_keys --vlad <VLAD_HEX>bs admin ssh list-users --authorized-keys-path /home/alice/.ssh/authorized_keysbs admin ssh-server add-user --vlad <VLAD_HEX> --os-user alicebs admin ssh-server list-usersbs admin tls add-service <SERVICE_CONFIG>bs admin tls list-servicesbs admin wireguard add-peer --interface wg0 --vlad <PEER_VLAD_HEX>bs admin wireguard list-peers --interface wg0bs admin acl reload

Send Encrypted Messages

BetterSign messages are sealed with the recipient encryption key from their plog and signed by the sender identity. The sealed file can be delivered out of band or handled by message workflows.

Use JSON output when inspecting message envelopes during development.

bs logs encrypt --sender <SENDER_LOG_ID> --recipient <RECIPIENT_LOG_ID> --text "Hello" -o hello.bsmsgbs logs encrypt --sender <SENDER_LOG_ID> --recipient <RECIPIENT_LOG_ID> --input secret.pdf -o secret.pdf.bsmsgbs logs encrypt --sender <SENDER_LOG_ID> --recipient <RECIPIENT_LOG_ID> --text "Hello" --output-format json -o hello.jsonbs logs decrypt --input hello.bsmsg -o hello.txtbs messages listbs messages read <MESSAGE_ID>

Use the Bootstrap Peer

Peers need an initial network entrypoint before they can discover other records. The Bootstrap Peer page shows the current public address.

After the first connection, BetterSign discovery and verified plog synchronization handle the rest of the peer lookup flow.

bs peer bootstrap --timeout 30bs peer config add-peer <MULTIADDR>bs peer config list-peersbs peer capabilities <MULTIADDR> --json