Lexe CLI

The Lexe CLI allows you to create and control self-custodial, always-online Lightning wallets from the command line.

With a single command $ lexe init, the Lexe CLI will generate a root seed, save it to ~/.lexe/seedphrase.txt, register an anonymous account with Lexe, and set up a mainnet Lightning node running inside a secure enclave inside Lexe's infrastructure, where only you have access to the funds. Your Lightning node is always online to receive payments, even if you aren't. Furthermore, node hosting is free.

Install

curl -fsSL https://lexe.app/install-cli.sh | bash

Quickstart

Option 1: Create a new wallet

lexe init

The seedphrase is saved to ~/.lexe/seedphrase.txt and auto-loaded on subsequent runs. Be sure to back up your seedphrase to a safe place.

Option 2: Control an existing wallet

Export credentials from the Lexe app (Menu > SDK clients), then set via:

LEXE_CLIENT_CREDENTIALS - Set in environment or .env file
--client-credentials - Pass directly in CLI
--client-credentials-path - Provide a path to a file with credentials

Verify your setup:

lexe node-info

Commands and CLI Options

See the top-level CLI help with $ lexe --help:

Lexe CLI - Create and control Lightning wallets from the command line.
   Lexe wallets are self-custodial and always online to receive payments.

Create a new mainnet wallet:
  $ lexe init
  The seedphrase is saved to ~/.lexe/seedphrase.txt and auto-loaded on
  subsequent runs. Be sure to back up your seedphrase to a safe place.

Control a wallet created from the Lexe mobile app:
  Export credentials from the app (Menu > SDK clients), then set via:
    • LEXE_CLIENT_CREDENTIALS     Set in environment or .env file
    • --client-credentials        Pass directly in CLI
    • --client-credentials-path   Path to file with client credentials

Verify your setup:
  $ lexe node-info

Precedence: CLI args > env vars > .env
  `.env` is loaded from the current or any parent directory.

Usage: $ lexe [OPTIONS] <COMMAND>

Commands:
  init                 Create a new Lexe wallet
  signup               Register with Lexe and perform initial provisioning
  provision            Provision wallet to latest enclave releases
  node-info            Get information about this Lexe node
  create-invoice       Create a BOLT 11 invoice to receive a Lightning payment
  pay-invoice          Pay a BOLT 11 invoice over Lightning
  create-offer         Create a BOLT 12 offer to receive Lightning payments
  pay-offer            Pay a BOLT 12 offer over Lightning
  get-payment          Get a payment by its created index
  wait-for-payment     Wait for a payment to reach a terminal state
  update-payment-note  Update the personal note on an existing payment
  sync-payments        Sync payments from the node to the local payments cache
  list-payments        List payments from local storage
  clear-payments       Clear all locally cached payment data for this wallet
  help                 Print this message or the help of the given subcommand(s)

Options:
      --network <NETWORK>
          The bitcoin network to use. [default: mainnet]

          [env: LEXE_NETWORK=]
          [possible values: mainnet, testnet3, regtest]

      --client-credentials <CLIENT_CREDENTIALS>
          The client credentials string exported from the Lexe app. [env: LEXE_CLIENT_CREDENTIALS]

      --client-credentials-path <CLIENT_CREDENTIALS_PATH>
          Path to a file containing the client credentials. [env: LEXE_CLIENT_CREDENTIALS_PATH]

      --root-seed <ROOT_SEED>
          Root seed as a 64-character hex string. [env: LEXE_ROOT_SEED]

      --root-seed-path <ROOT_SEED_PATH>
          Path to a file containing the root seed (hex or mnemonic). [env: LEXE_ROOT_SEED_PATH]

      --lexe-data-dir <LEXE_DATA_DIR>
          Data directory for persisted state. [default: ~/.lexe] [env: LEXE_DATA_DIR]

      --rust-log <RUST_LOG>
          Log level: error, warn, info, debug, trace. [default: info] [env: RUST_LOG]

      --without-db
          Use wallet without local payments persistence

  -h, --help
          Print help (see a summary with '-h')

Command Reference

For any command, see detailed help with $ lexe <command> --help.

`init`

Creates a new Lexe wallet.

Generates a fresh seedphrase, persists it to the Lexe data dir,
registers a wallet with Lexe, and provisions a new user node.

Idempotent: safe to call multiple times.

Usage: $ lexe init

Options:
  -h, --help
          Print help (see a summary with '-h')

`signup`

Register with Lexe and perform initial provisioning.
Requires the root seed.

This command exists mostly to support specialized flows.
`lexe init` is usually what you want instead.

Idempotent: safe to call even if already signed up.

Usage: $ lexe signup [OPTIONS]

Options:
      --partner-pk <PARTNER_PK>
          Partner public key (hex) to earn a share of this wallet's fees

  -h, --help
          Print help (see a summary with '-h')

`provision`

Ensure the wallet is provisioned to all recent trusted releases.

Should be called every time the wallet is loaded to ensure the node
is running the most up-to-date enclave software.

Idempotent: safe to call multiple times.

Usage: $ lexe provision

Options:
  -h, --help
          Print help (see a summary with '-h')

`node-info`

Get information about this Lexe node

Usage: $ lexe node-info

Options:
  -h, --help  Print help

`create-invoice`

Create a BOLT 11 invoice to receive a Lightning payment

Usage: $ lexe create-invoice [OPTIONS]

Options:
      --amount-sats <AMOUNT_SATS>          Amount in satoshis.
                                           Omit for amountless invoice.
      --description <DESCRIPTION>          Description to encode in the invoice.
                                           Visible to sender when scanned.
      --expiration-secs <EXPIRATION_SECS>  Invoice expiration in seconds.
                                           [default: 86400 = 1 day]
  -h, --help                               Print help

`pay-invoice`

Pay a BOLT 11 invoice over Lightning

Usage: $ lexe pay-invoice [OPTIONS] <INVOICE>

Arguments:
  <INVOICE>  The BOLT 11 invoice to pay

Options:
      --fallback-amount-sats <FALLBACK_AMOUNT_SATS>
          Amount to pay if invoice has no amount.
          Required for amountless invoices.
      --note <NOTE>
          Personal note (not visible to receiver, max 200 chars)
  -h, --help
          Print help

`create-offer`

Create a BOLT 12 offer to receive Lightning payments.

Unlike invoices, offers are reusable: multiple payments can be
made to it, including from multiple payers.

Usage: $ lexe create-offer [OPTIONS]

Options:
      --description <DESCRIPTION>
          Description shown to payers when they scan the offer.
          Maximum length: 512 UTF-8 bytes.

      --min-amount-sats <MIN_AMOUNT_SATS>
          Minimum payment amount in satoshis.
          If not set, the payer can send any amount.

      --expiration-secs <EXPIRATION_SECS>
          Offer expiration in seconds from now

  -h, --help
          Print help (see a summary with '-h')

`pay-offer`

Pay a BOLT 12 offer over Lightning

Usage: $ lexe pay-offer [OPTIONS] --amount-sats <AMOUNT_SATS> <OFFER>

Arguments:
  <OFFER>
          The BOLT 12 offer to pay

Options:
      --amount-sats <AMOUNT_SATS>
          The amount to pay in satoshis.
          Must satisfy the offer's minimum amount if set.

      --note <NOTE>
          Personal note stored locally, not visible to receiver.
          Maximum length: 512 UTF-8 bytes.

      --payer-note <PAYER_NOTE>
          Note sent to the receiver with the payment.

          Maximum length: 512 UTF-8 bytes.

  -h, --help
          Print help (see a summary with '-h')

`get-payment`

Get a payment by its created index.

Fetches the payment directly from the user node (not from local storage).

Usage: $ lexe get-payment <INDEX>

Arguments:
  <INDEX>
          The payment's created index

Options:
  -h, --help
          Print help (see a summary with '-h')

`wait-for-payment`

Wait for a payment to reach a terminal state (completed or failed).

Polls the node with exponential backoff until the payment finalizes
or the timeout is reached. Defaults to 600 seconds (10 minutes).

If already finalized, we still fetch the payment
to ensure we have the latest metadata.

Usage: $ lexe wait-for-payment [OPTIONS] <INDEX>

Arguments:
  <INDEX>
          The payment index to wait on

Options:
      --timeout-secs <TIMEOUT_SECS>
          Timeout in seconds. [default: 600, max: 86400]

  -h, --help
          Print help (see a summary with '-h')

`update-payment-note`

Update the personal note on an existing payment.

The note is stored on the user node and is not visible to the counterparty.

Usage: $ lexe update-payment-note [OPTIONS] <INDEX>

Arguments:
  <INDEX>
          The payment index

Options:
      --note <NOTE>
          The new note (omit to clear, max 200 chars)

  -h, --help
          Print help (see a summary with '-h')

`sync-payments`

Sync payments from the user node to the local payments cache.

Usage: $ lexe sync-payments

Options:
  -h, --help
          Print help (see a summary with '-h')

`list-payments`

List payments from local storage with cursor-based pagination.

Defaults to descending order (newest first) with a limit of 100.
Use `sync-payments` to fetch the latest data from the node first.

Usage: $ lexe list-payments [OPTIONS]

Options:
      --filter <FILTER>
          Filter: all, pending, completed, failed, finalized. [default: all]

          [default: all]

      --order <ORDER>
          Sort order: asc or desc. [default: desc]

      --limit <LIMIT>
          Max number of payments to return. [default: 100]

      --after <AFTER>
          Start after this payment index (for pagination)

  -h, --help
          Print help (see a summary with '-h')

`clear-payments`

Clear all locally cached payment data for this wallet.

Remote data on the node is not affected.
Use `sync-payments` to re-populate after clearing.

Usage: $ lexe clear-payments

Options:
  -h, --help
          Print help (see a summary with '-h')