Guides

CLI reference

oceanln is the command-line frontend over oceanln-common — for humans, scripts, and AI. Every command that touches your key resolves the seed the same way.

generate

Generates a fresh 24-word BIP39 mnemonic (256 bits of entropy from the OS CSPRNG) and prints it once:

oceanln generate

This single seed does double duty:

  • feed it to oceanln payout to derive your mining address and sign, and
  • feed it to the Lexe sidecar as its root seed (LEXE_ROOT_SEED_PATH=<file> lexe-sidecar), so the same wallet runs your Lightning node.

The mnemonic goes to stdout; the warning and usage hint go to stderr, so oceanln generate --json yields a clean {"mnemonic": "..."}. It is never written to disk — write it down yourself.

init

init --generate is the one-shot onboarding: generate a seed, derive the mining address, provision the wallet, and persist the seed to ~/.config/oceanln/seed. Drop --generate to onboard an existing seed from stdin; add --dry-run to derive without any network call. See Getting started for the full walk-through.

offer

Creates a payable BOLT12 offer on your node and prints it:

oceanln offer --description "OCEAN payout"   # create a payable BOLT12 offer, print it
info

The offer must come from a running node — a BOLT12 offer built offline from a key is structurally valid but unpayable (no node answers invoice requests for it), so the flow uses the node's create_offer instead.

payout

One command does the whole setup. It resolves your seed, then:

  1. derives your BIP84 mining address (m/84'/0'/0'/0/0) — the address you register with OCEAN, provably controlled by the same seed it signs with;
  2. asks the node to create a payable BOLT12 offer with your --description (via the sidecar's POST /v2/node/create_offer);
  3. BIP-322 signs the OCEAN --message verbatim with the derived key;
  4. prints the address, the offer, and the base64 signature (add --json for a machine-readable object).
oceanln payout \
  --message "Configure OCEAN payout to lno1... at block 840000" \
  --description "my pool payout" \
  --min-amount 1000

Order matters: the offer is created before signing, so if the sidecar is down the flow aborts without using your mnemonic on a message you couldn't submit. --min-amount is in satoshis; omit it for a variable-amount offer. --path overrides the default derivation path.

Already have an offer? Sign for it directly

Pass --offer <lno1...> and payout skips offer creation entirely — no sidecar is contacted, it just derives the address and BIP-322 signs the message (fully offline):

oceanln payout --offer lno1... --message "<exact OCEAN message>"

--offer is mutually exclusive with --description / --min-amount.

Seed resolution

init, offer, and payout resolve the seed in this order, stopping at the first that yields one:

  1. --seed-file <path> — an explicit override (read, and for init also the write target);
  2. piped stdin — echo "$SEED" | oceanln … or the test harness;
  3. the persisted managed file — $XDG_CONFIG_HOME/oceanln/seed, else ~/.config/oceanln/seed, if present;
  4. an interactive hidden prompt (TTY only).

The seed file is plaintext but written 0600 (owner-only); a group/world-readable seed file is rejected with a chmod 600 hint. init refuses to overwrite a file holding a different seed unless you pass --force, and --no-store skips persistence entirely for a one-off provisioning.

Thin build

Drop the SDK for a smaller dependency tree — only generate + payout (the sidecar client):

cargo build --no-default-features -p oceanln-common -p oceanln-cli