Initialize a project

The lomi init command bootstraps a lomi. integration in your project directory. It creates SDK client setup, example code, and a .env file with your API credentials.

Requires prior lomi login (or LOMI_ACCESS_TOKEN in CI).

Usage

cd my-project
lomi init

Options

Flag	Description
`-y, --yes`	Headless mode (requires `--environment`, `--language`, `--api-key`)
`-e, --environment`	`production` or `sandbox`
`-L, --language`	`ts` or `js`
`--api-key`	Secret API key written to `.env`
`--skip-package-install`	Skip `npm install` of SDK dependencies
`--skip-rules-install`	Skip agent rules install (`--yes` installs Cursor + llms.txt by default)
`--with-ui <name>`	Install a lomi. UI component after scaffold (headless)
`--skip-ui-install`	Skip lomi. UI install prompt
`[path]`	Project directory (default: current directory)

Headless example (CI)

lomi init --yes \
  --environment sandbox \
  --language ts \
  --api-key lomi_sk_test_xxx \
  --skip-package-install \
  --skip-rules-install

with lomi. UI (headless)

lomi init --yes \
  --environment sandbox \
  --language ts \
  --api-key lomi_sk_test_xxx \
  --with-ui payment-provider-selector \
  --skip-package-install

Requires Node.js and shadcn in the target project (or pass --yes so shadcn init runs non-interactively).

Interactive flow

When run interactively, lomi init prompts for:

Environment: Production or Sandbox (sets LOMI_API_URL)
Language: TypeScript or JavaScript for generated examples
API key: Your secret key from the Merchant Portal

It may also offer to run lomi install-rules if you haven't installed agent rules yet, and optionally install a lomi. UI checkout component via lomi ui.

Files created

File	Purpose
`.env`	`LOMI_SECRET_KEY`, `LOMI_WEBHOOK_SECRET` placeholder, `LOMI_API_URL`
`lib/lomi./client.{ts\|js}`	Initialized SDK client loading from `.env`
`examples/create-checkout-session.{ts\|js}`	Checkout session creation example
`examples/webhook-handler.{ts\|js}`	Basic webhook handler example
`examples/embed-checkout.html`	Modal embed example, replace `CHECKOUT_URL` after `lomi checkout create`
`lomi.config.ts`	Project-level lomi. configuration

Example .env:

LOMI_SECRET_KEY=lomi_sk_test_xxx
LOMI_WEBHOOK_SECRET=whsec_your_webhook_secret_here
LOMI_API_URL=https://sandbox.api.lomi.africa

Keep secrets out of git

Add .env to your .gitignore. Never commit secret API keys or webhook secrets.

Dependencies

If package.json exists (or is created), lomi init installs:

@lomi./sdk
dotenv

Use --skip-package-install to skip this step in CI and install manually.

After init

Review generated examples

Open lib/lomi./client.ts and the files in examples/.

Add your webhook secret

Replace the LOMI_WEBHOOK_SECRET placeholder in .env with the signing secret from the Merchant Portal.

Test webhooks locally

lomi dev

Point your dashboard webhook URL to a tunnel (e.g. ngrok) or use the local server during development. See Local development server.

Verify CLI auth

lomi status

Prerequisites

lomi login completed (or LOMI_ACCESS_TOKEN set)
A secret API key from the Merchant Portal (lomi_sk_test_… or lomi_sk_live_…)