Getting started

The lomi. CLI is distributed via npm as lomi.cli. It helps you authenticate with lomi., scaffold SDK projects, test webhooks locally, create checkout sessions and payment links, and install AI agent rules.

Who this is for

The lomi. CLI is for developers integrating the hosted merchant API from your terminal, authenticate, scaffold SDK projects, test webhooks, and create sandbox checkouts.

It is not for operating lomi.’s internal platform, the admin dashboard, or self-hosting payment processing. Merchants who only use the web dashboard do not need the CLI.

Both lomi and lomi. work as command names after install.

Installation

npm (recommended)

Requires Node.js 18+ (used only to download the native binary on install).

npm install -g lomi.cli

Or with pnpm:

pnpm add -g lomi.cli

On npm install, the package downloads the correct native binary for your platform from GitHub Releases.

Homebrew

Homebrew support is available via the project formula. After a release is published:

brew tap lomiafrica/tap
brew install lomi

You can also install from the repo formula when developing locally (update SHA256 checksums after each release).

From source

git clone https://github.com/lomiafrica/lomi.
cd lomi./apps/cli
cargo install --path .

Verify installation

lomi --version
lomi --help

Troubleshooting install

Symptom	Likely cause	What to do
`lomi: command not found` after `npm install -g`	npm global bin not on `PATH`	Run `npm prefix -g` and add that `bin` directory to your shell `PATH`, or use `npx lomi.cli --version`
Installed but `lomi --version` fails with glibc / version `GLIBC_X.XX' not found	Prebuilt binary targets a newer glibc than your Linux distro	Install via Homebrew, download a matching GitHub Release binary, or build from source with Rust on the same machine
Binary runs on macOS but not on older Linux CI images	CI runners often ship older glibc	Use the source build in CI, or a newer runner image (glibc ≥ 2.39 for npm-published Linux binaries at time of writing)

npm only needs Node.js 18+ to download the native binary; the CLI itself does not run on Node. If npm install -g lomi.cli succeeds but the binary cannot execute, treat it as a platform compatibility issue, not a Node version issue.

Supported platforms

Platform	Install method
macOS (Apple Silicon)	npm, Homebrew, GitHub Release
macOS (Intel)	npm, Homebrew, GitHub Release
Linux (x64)	npm, Homebrew, GitHub Release
Windows (x64)	Coming soon

Quick start

Log in

lomi login

Opens a browser device-authorization flow and saves a CLI token globally. See Authenticate.

Check status

lomi status

Verifies your stored token and connectivity to lomi.. API.

Scaffold a project

cd my-app
lomi init

Creates SDK client setup, checkout and webhook examples, and a .env file. See Initialize a project.

Install AI agent rules (optional)

lomi install-rules

Installs Cursor rules, CLAUDE.md, AGENTS.md, VS Code instructions, and llms.txt. See Install agent rules.

Listen for webhooks (recommended)

lomi listen http://localhost:3000/webhooks

Receives real sandbox webhooks via cloud relay, no ngrok. See Listen for webhooks.

Run local webhook server

lomi dev

Starts a webhook receiver on http://localhost:4242/webhook. See Local development server.

Command overview

Command	Description
`lomi login`	Browser authentication
`lomi logout`	Clear credentials for a profile
`lomi whoami`	Show current profile
`lomi status`	Check login and API connectivity
`lomi init`	Scaffold SDK project files
`lomi quickstart`	Golden-path checks and next steps
`lomi listen`	Cloud webhook relay (sandbox-first)
`lomi dev`	Local webhook development server
`lomi probe`	Integration health checks
`lomi webhooks list`	List webhook endpoints
`lomi webhooks test`	Send a test webhook event
`lomi products list`	List products and prices
`lomi transactions list`	List recent transactions
`lomi transactions get`	Get a transaction by ID
`lomi refunds create`	Refund a completed transaction
`lomi refunds list` / `refunds get`	List or retrieve refunds
`lomi checkout create`	Create a hosted checkout session
`lomi payments create`	Create a payment link
`lomi install-rules`	Install AI agent documentation
`lomi update`	Update `@lomi./sdk` in current project
`lomi list-profiles`	List saved auth profiles
`lomi switch`	Change active profile

Full reference: Command reference.

Global options

These flags work with any command:

Flag	Description
`--profile <name>`	Profile to use (default: `default`)
`-a, --api-url <url>`	Override API base URL
`-l, --log-level <level>`	`debug`, `info`, `warn`, `error`
`--skip-telemetry`	Opt out of telemetry
`--json`	Emit machine-readable JSON (also default when stdout is not a TTY)
`-h, --help`	Help for the CLI or a subcommand
`--version`	Print version

Two kinds of credentials

CLI token vs API key

lomi login stores a CLI token in your global config, used by CLI commands like status, checkout create, and dev.

lomi init writes your secret API key (LOMI_SECRET_KEY) into the project .env file, used by the SDK inside your application code.

These are different credentials serving different purposes.

Next steps

Authenticate: device flow, profiles, CI
Initialize a project: SDK scaffolding
Command reference: all commands and flags
Configuration: config file paths and environment variables
API integration: HTTP and SDK integration guide

Getting started

On this page