CLI Quickstart

This documentation is primarily geared towards developers rather than end-users. (Operators looking to run the mail services themselves should start at Running a mail server.) To follow the examples, you’ll need the sithbit CLI built from the sithbit-solana repository: clone the repo and build it with cargo build -p mail-client -r, which produces the sithbit binary at 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

It walks you through the two things you need — a Solana RPC endpoint and a signing wallet, offering to generate a fresh wallet if you don’t already have one — checks that the wallet holds enough SOL to claim a mailbox (funding it automatically from the faucet on devnet-style clusters, or walking you through a transfer on mainnet), and can optionally claim your on-chain mailbox in the same pass, then prints the next steps to start receiving mail. The wizard is re-runnable and non-destructive: it shows your current settings, changes only what you explicitly ask it to, and never overwrites an existing keypair, so running it again on a configured machine is safe. Pressing Enter at any prompt keeps the current value (with one exception: on a machine with no wallet yet, Enter at the endpoint prompt accepts a suggested default — mainnet for release builds, devnet for development builds); the mailbox step — the one that spends SOL — defaults to skip, so a scripted or piped run never sends a transaction. See First-run setup for a 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

Talking to the chain also needs a Solana RPC endpoint — the URL of a server that answers reads and forwards transactions for one of Solana’s networks (see Solana clusters and RPC endpoints for what the public clusters are and which one SithBit runs on). Configure one with sithbit config set --url <cluster> (e.g. https://api.devnet.solana.com), or point a JSON_RPC_URL environment variable at one directly.¹

Creating a wallet

You’ll need a cryptographic keypair / 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.

Even though there is no domain portion of the address, i.e., [email protected], your standalone public key address is already a legitimate email address in the system, although you will need to create a mailbox for it and at least one frombox before emails can be routed to your address. A frombox is keyed by a pair: your wallet address as the recipient, and a sender’s “from” address — but only the recipient side needs to be an on-chain wallet. The sender’s “from” address is just a plain, off-chain RFC822-compliant address string (e.g. [email protected], or any other domain) — it never has to resolve to a Solana keypair.

Neither step above needs the Solana CLI/SDK installed at all — sithbit config and sithbit wallet create are a complete substitute for it in this workflow.

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. ↩