CLI reference

Reference for the command-line tools shipped with zentalk-node and zentalk-api. Network daemons (relay, mesh-api, dht-bootstrap) are covered in Node binaries and ports.

zentalk-client

Anonymous messaging client that connects to a relay using zero-knowledge proofs. The relay verifies membership without learning which registered identity connected.

Flags

Flag	Default	Description
`-relay`	`localhost:8080`	Relay server address
`-cmd`	`connect`	Command to run (see below)
`-identity`	`./zkp-identity.json`	Path to the identity file
`-proving-key`	`./zkp-keys/proving_key.bin`	Path to the ZK proving key
`-username`	—	Username (for `register`, `register-username`, `send`)
`-message`	—	Message body (for `send`)

Commands

Command	Description
`register`	Register your identity with the relay (creates the identity file on first run)
`connect`	Connect anonymously to the relay; requires prior registration and the proving key
`status`	Show local identity status (commitment, registration state, tree index)
`register-username`	Register a username so others can look up your address
`advertise-key`	Publish your public key so others can send you encrypted messages
`send`	Send an encrypted message to a username
`listen`	Listen for incoming messages

All commands except register and status require the proving key generated by zkp-setup.

# One-time: register an identity with the relay
zentalk-client -cmd register -relay relay.example.com:9001 -username alice

# Publish your key and username
zentalk-client -cmd advertise-key -relay relay.example.com:9001
zentalk-client -cmd register-username -relay relay.example.com:9001 -username alice

# Send and receive
zentalk-client -cmd send -relay relay.example.com:9001 -username bob -message "hello"
zentalk-client -cmd listen -relay relay.example.com:9001

zentalk-reputation-cli

Operator tool for inspecting and mutating the persistent peer-reputation store (BadgerDB) used by mesh nodes. Intended for incident response: inspect a peer’s score, clear a record, or apply a manual ban.

The store path is derived from --datadir (default ./data) as <datadir>/reputation/badger. Stop the node first, or point at a copy — BadgerDB is single-writer.

Subcommand	Description
`list`	List banned peers with score, ban expiry, and reason
`show <peerID>`	Show one peer’s score and ban state
`clear <peerID>`	Delete the peer’s reputation record
`ban --dur <duration> --reason <tag> <peerID>`	Ban a peer (defaults: `--dur 24h`, `--reason operator`)
`whitelist <peerID>`	Clear any existing ban for the peer

zentalk-reputation-cli --datadir /var/lib/zentalk/data list
zentalk-reputation-cli --datadir /var/lib/zentalk/data show 12D3KooW...
zentalk-reputation-cli --datadir /var/lib/zentalk/data ban --dur 48h --reason spam 12D3KooW...
zentalk-reputation-cli --datadir /var/lib/zentalk/data whitelist 12D3KooW...

ban flags must precede the peer ID, as shown above.

zkp-setup

Generates the Groth16 proving and verifying keys for the RLN (Rate Limiting Nullifier) zero-knowledge circuit used by relay and zentalk-client.

Flag	Default	Description
`-depth`	`20`	Merkle tree depth; max users = 2^depth (20 ≈ 1M)
`-output`	`./zkp-keys`	Output directory for `proving_key.bin` and `verifying_key.bin`
`-force`	`false`	Overwrite existing keys

zkp-setup -output ./zkp-keys

Distribute proving_key.bin to clients and verifying_key.bin to relays.

zentalk-api server binaries

The zentalk-api repository ships the API server plus operational utilities under cmd/:

Binary	Purpose
`api-server`	The REST + WebSocket API server; configured entirely via environment variables (only flag: `-version`). See the REST API reference.
`zentalk-admin`	Closed-beta administration: `allowlist add/remove/list/hash` for the phone-hash allowlist. DSN via `--db`, `ZENTALK_ADMIN_DB`, or `DATABASE_URL`.
`zentalk-keytool`	Relay keypair management: `generate`, `encrypt`, `decrypt`, `info`. Keys are RSA-4096 encrypted at rest with Argon2id + AES-256-GCM; passphrases must be at least 32 characters.
`federation-keygen`	Generates the encrypted Ed25519 federation server identity. See Federation setup.
`migrate`	Database migrations: `-cmd up
`encrypt-db`	One-shot message-encryption migration: `-db`, `-key` (or `ZENTALK_DB_ENCRYPTION_KEY`), `-dry-run`, `-batch`, `-decrypt` for reversal.
`db-encrypt-backfill`	Checkpointed backfill of legacy plaintext rows to ciphertext columns: subcommands `messages`, `edit-history`, `all`, `status`, `resume`; dry-run by default (`--no-dry-run` to commit). Requires `ZENTALK_DB_ENCRYPTION_KEY`.

Each binary prints detailed usage with -h or help.