CLI quickstart

This reference is for developers and power users. Most people should use the graphical clients; operators deploying the mail services should start with Running a mail server.

To follow the examples, clone the SithBit repository and build the sithbit CLI:

cargo build -p mail-client -r

The binary is written to target/release/sithbit.

The fast path: sithbit setup

If you just want to get going, run the guided setup wizard and follow the prompts:

sithbit setup

The wizard configures a Solana RPC endpoint and a signing wallet, generating a fresh wallet if needed. It checks whether the wallet holds enough SOL to claim a mailbox, uses the faucet on devnet-style clusters or explains the required transfer on mainnet, and can optionally claim the on-chain mailbox in the same pass. It then prints the next steps for receiving mail.

The wizard is safe to rerun: it shows current settings, changes only what you approve, and never overwrites an existing keypair. Pressing Enter keeps the current value. The only exception is a machine with no wallet, where Enter at the endpoint prompt accepts the suggested network (mainnet in release builds, devnet in development builds). The mailbox step spends SOL and therefore defaults to skip; a scripted or piped run never sends a transaction. See First-run setup for the full walkthrough.

The rest of this page does the same two steps by hand — useful when you want to understand exactly what setup writes, or to script the pieces individually.

Configuring a Solana RPC endpoint

The CLI needs a Solana RPC endpoint: a server that answers reads and forwards transactions for a Solana network. See Solana clusters and RPC endpoints for the available public clusters and SithBit’s deployment status. Configure an endpoint with sithbit config set --url <cluster> (for example, https://api.devnet.solana.com), or set JSON_RPC_URL.¹

Creating a wallet

You also need a cryptographic keypair, commonly called a wallet. Its public key becomes your first email address. sithbit can generate one directly:

sithbit wallet create
# Wallet keypair written to '/home/you/.config/solana/id.json'
# Address: 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03

By default this writes to the path sithbit config get reports as your keypair path.² Pass --outfile <path> to write elsewhere; sithbit wallet create refuses to overwrite an existing keypair file unless you also pass --force.

The bare public key is already a valid SithBit address; it does not need an @domain suffix. To receive mail, it needs a mailbox and a frombox with at least one stamp for the sender. A frombox is keyed by the sender’s off-chain From string and the recipient’s on-chain wallet. Only the recipient side must resolve to a Solana keypair.

Neither step above requires the Solana CLI or SDK. For this workflow, sithbit config and sithbit wallet create provide everything you need.

1. If you already have the Solana CLI installed, solana config set --url <cluster> writes the same config file. ↩

2. If you already have the Solana CLI/SDK installed, solana-keygen new followed by solana-keygen pubkey gets you the same keypair file and address. ↩