Run loyalty work without memorizing the API.

Pin the stable release before you automate it.

The package name is @loyumi/cli, version 1.5.1, and the executable is loyumi. Add it to each project and run it through npx so every teammate and CI job uses the reviewed version.

npm install --save-dev https://docs.loyumi.com/downloads/loyumi-cli-1.5.1.tgz
npx loyumi --version

Four commands. One safe project check.

1. 1

   Put the key in your shell

   Use a Sandbox key. The CLI reads it from an environment variable and never writes it into project configuration.

2. 2

   Run guided setup

   loyumi init asks only for missing project settings and writes .loyumi/config.json.

3. 3

   Let doctor inspect the setup

   loyumi doctor validates the project config and API version, checks the referenced credential, and confirms API connectivity without sending a real customer record. Add --offline to skip the network check.

4. 4

   Review the safe view

   loyumi config show displays effective project settings and recursively replaces secret-like values with [REDACTED].

export LOYUMI_API_KEY="<sandbox-api-key>"
npx loyumi init
npx loyumi doctor
npx loyumi config show

Prove one real loop against your official Loyumi Sandbox.

quickstart proof is an opt-in, state-changing command. It accepts only https://app.loyumi.com/api/v1, rejects redirects, and does not use a local sample server, fixture response, or mock fallback. Run it only in a Sandbox where synthetic test data is allowed.

npx loyumi quickstart proof \
  --program "$PUBLISHED_SANDBOX_PROGRAM_ID" \
  --json \
  --non-interactive

Required credential scopes are exports:read, programs:read, members:read, members:write, events:write, and transactions:read. An existing published Sandbox program with an earn rule is also required. Reruns with the same program and optional --proof-id reuse the same synthetic identity and transaction; use a new proof ID before changing --amount-minor or --notice-version.

Easy defaults, with every important control available.

Interactive terminals receive a prompt for a missing environment ID. Scripts and non-interactive terminals do not. Supply required values with flags when a person cannot answer.

npx loyumi init \
  --environment "$LOYUMI_ENVIRONMENT_ID" \
  --api-key-env LOYUMI_API_KEY \
  --timeout-ms 10000 \
  --retries 2 \
  --non-interactive

npx loyumi doctor [--config <path>] [--offline] [--json]
npx loyumi config show [--config <path>] [--json]

Resolution is predictable: --config <path> wins; otherwise the CLI searches from the current folder through its parents for the nearest .loyumi/config.json. Official defaults use https://app.loyumi.com and LOYUMI_API_KEY. Custom deployments must repeat the exact --trust-origin and/or --trust-api-key-env value on every credential-using command, including CI; trust is never saved. Change environment, URL, timeout, or retries by running init deliberately, rather than through a hidden runtime override.

Every command accepts --config, --json, --non-interactive, and --help; loyumi --version prints the installed CLI version. --non-interactive matters to init, the only command that can prompt.

Create identity, then govern each program membership explicitly.

Use your own stable customer ID. Values in angle brackets below are placeholders to replace, not sample merchant or customer records.

npx loyumi members list   --status active   --limit 50

npx loyumi members create \
  --external-id "$CUSTOMER_ID" \
  --name "$DISPLAY_NAME" \
  --consent opted_in \
  --notice-version "$IDENTITY_NOTICE_VERSION"

npx loyumi members enroll \
  --external-id "$CUSTOMER_ID" \
  --program "$PROGRAM_ID" \
  --notice-version "$REWARDS_NOTICE_VERSION" \
  --evidence '{"source":"<consent-capture-channel>"}' \
  --idempotency-key "$ENROLLMENT_KEY"

npx loyumi members unenroll \
  --external-id "$CUSTOMER_ID" \
  --program "$PROGRAM_ID" \
  --reason "$APPROVED_WITHDRAWAL_REASON" \
  --evidence '{"source":"<withdrawal-channel>"}' \
  --idempotency-key "$UNENROLLMENT_KEY"

npx loyumi members get --external-id "$CUSTOMER_ID"

npx loyumi members update \
  --external-id "$CUSTOMER_ID" \
  --name "$UPDATED_DISPLAY_NAME" \
  --request-id "$TRACE_ID"

For a reviewed JSON request body, use exactly one of --file <path> or --stdin with members create or members update. This also keeps email addresses and phone numbers out of shell history. Add --dry-run to validate and display the redacted request without sending it.

Govern a privacy deletion

members delete requires the dedicated members:delete scope and an idempotency key derived from the verified privacy case. It tombstones the member profile, scrubs known structured identifier copies, and governance-scrubs stored idempotency receipt response snapshots that contain those identifiers while preserving the receipt's operation identity. Governed ledger, transaction, consent, and audit records remain explainable, while merchant-supplied references or evidence remain subject to the merchant's approved retention policy. Do not describe this as guaranteed global de-identification of arbitrary merchant-authored text.

npx loyumi members delete   --external-id <external-customer-id>   --deletion-reference <verified-privacy-case-id>   --reason "<approved-erasure-reason>"

Move exact business facts in; pull governed data out.

Award a completed purchase

Amounts use positive integer minor units. events earn uses --source as the default idempotency key; use --idempotency-key only when your stable business-event identity needs a different value. --channel defaults to web and also accepts store or app. Optional flags are --coupon, --request-id, and --dry-run.

npx loyumi events earn \
  --program "$PROGRAM_ID" \
  --external-id "$CUSTOMER_ID" \
  --amount-minor "$ORDER_AMOUNT_MINOR" \
  --channel web \
  --source "$ORDER_ID"

Send a registered engagement event

The event type must already exist in the selected environment. --source is also the default idempotency key. Optional flags are --occurred-at <ISO>, --attributes <JSON object>, --idempotency-key, --request-id, and --dry-run. Use exactly one of --file or --stdin to supply the complete JSON body.

npx loyumi events send \
  --type "$REGISTERED_EVENT_TYPE" \
  --external-id "$CUSTOMER_ID" \
  --source "$SOURCE_ID"

Send normalized commerce and item-selected returns

Use a reviewed JSON file when the purchase includes line references, currency, store, market, tax, discounts, shipping, tender, customer tags, or other normalized context. For an item-selected return, identify the original lineReference and returned quantity; Loyumi derives and verifies the attributable amount and points. The purchase source reference and return reference become their default idempotency keys.

npx loyumi events earn --file ./reviewed-purchase.json
npx loyumi events return --file ./reviewed-return.json

Pull a portable exit bundle

The default command writes the complete API response to the selected file. For pagination, use --collection <name>, then pass the returned cursor with --after <cursor>. --limit accepts 1 through 5,000. Existing files require --force.

npx loyumi exports pull \
  --output ./loyumi-portability-export.json

The CLI covers the critical governed-value control paths.

The stable downloadable @loyumi/cli 1.5.1 package includes redemption, two-person adjustment, program-configuration, exact ledger-close, and read-only list operations. These commands call the public API; they do not weaken credential scopes, readiness gates, or approval rules.

npx loyumi redemptions list --program <program-id> --state reserved
npx loyumi adjustments list --state pending_approval

npx loyumi redemptions quote   --program <program-id>   --external-id <external-customer-id>   --source <stable-cart-reference>   --reward <reward-id>

npx loyumi redemptions reserve   --quote <quote-id>   --idempotency-key <stable-reservation-key>

npx loyumi redemptions commit   --redemption <redemption-id>   --provider <fulfillment-connector-name>

npx loyumi adjustments request   --file <reviewed-adjustment.json>   --idempotency-key <stable-case-id>

npx loyumi adjustments approve   --adjustment <adjustment-id>   --approval-reference <approval-case-id>   --note "<recorded-decision>"

npx loyumi programs validate --file <program-manifest.json>
npx loyumi programs revision-create   --program <program-id>   --file <program-manifest.json>   --if-match '<current-etag>'   --idempotency-key <stable-revision-id>
npx loyumi programs revision-publish   --program <program-id>   --version <revision-number>   --if-match '<current-etag>'   --idempotency-key <stable-publish-id>

Stage first. Inspect every exception. Apply in resumable chunks.

Use the import lifecycle for member opening balances. Staging validates up to 5,000 records without changing a balance. Status exposes accepted rows and row-level exceptions. Apply creates only missing members in bounded, idempotent chunks and never overwrites an existing member.

npx loyumi imports list --program <program-id> --status exceptions_review

npx loyumi imports stage \
  --program "$PROGRAM_ID" \
  --file ./members-opening-balances.json \
  --idempotency-key "$IMPORT_BATCH_KEY"

npx loyumi imports status \
  --batch "$IMPORT_BATCH_ID" \
  --status exception

npx loyumi imports apply \
  --batch "$IMPORT_BATCH_ID" \
  --limit 100 \
  --idempotency-key "$IMPORT_APPLY_KEY"

1. 1

   Prepare the governed file

   Use schemaVersion: "loyumi.members/v1" and a records array. Keep the file out of source control because it contains customer and balance data.

2. 2

   Stage without mutation

   The service validates the complete batch and binds its checksum to the idempotency key. A redacted dry run is available before sending.

3. 3

   Resolve exceptions

   Inspect exception rows before applying. Correct the source file and stage a new batch instead of hiding invalid data.

4. 4

   Apply a bounded chunk

   Repeat apply with a new stable chunk key until the batch reports completion. The batch cursor makes interrupted work resumable.

Investigate real value without opening the console.

These 1.5.1 commands expose the common back-office reads. Every list accepts --limit <1-200> and the opaque --cursor returned by the previous response. Never decode or edit a cursor.

npx loyumi transactions list   --program <program-id>   --from <ISO-timestamp>   --to <ISO-timestamp>

npx loyumi transactions get --transaction <transaction-id>
npx loyumi operations list --type <operation-type> --status <operation-status>
npx loyumi operations get --operation <operation-id>

npx loyumi audit list   --target-type <target-type>   --target-id <target-id>

npx loyumi analytics ledger-summary   --program <program-id>   --from <ISO-timestamp>   --to <ISO-timestamp>

npx loyumi reports ledger-close   --program <program-id>   --from <ISO-timestamp>   --to <ISO-timestamp>   --request-id <close-run-id>

Create disabled. Save the secret. Activate. Test. Inspect. Retry.

Endpoint and delivery commands preserve the same public webhook lifecycle. Create and rotate reveal the signing secret only in the original result and print a reminder to save it immediately.

npx loyumi webhooks endpoints create   --url <public-https-endpoint>   --event points.earned   --event redemption.committed   --event adjustment.posted   --idempotency-key <stable-create-key>

# Save the one-time signing secret in your secret manager.
npx loyumi webhooks endpoints update   --endpoint <endpoint-id>   --status active   --idempotency-key <stable-activate-key>

npx loyumi webhooks endpoints rotate   --endpoint <endpoint-id>   --idempotency-key <stable-rotation-key>

npx loyumi webhooks endpoints test   --endpoint <endpoint-id>   --idempotency-key <stable-test-key>

npx loyumi webhooks deliveries list   --endpoint <endpoint-id>   --status failed

npx loyumi webhooks deliveries retry   --delivery <delivery-id>   --idempotency-key <stable-retry-key>

npx loyumi webhooks endpoints list --limit 50
npx loyumi webhooks endpoints get --endpoint <endpoint-id>

Add --dry-run to create, update, rotate, test, or retry to validate and show a redacted request without sending it.

Generate the embed instead of hand-writing it.

Choose rewards for a Studio-composed experience, or balance, tier-progress, catalog, or activity for one focused surface.

npx loyumi widgets snippet \
  --deployment "$LOYUMI_DEPLOYMENT_ID" \
  --component rewards

npx loyumi widgets snippet \
  --deployment "$LOYUMI_DEPLOYMENT_ID" \
  --component rewards \
  --session-endpoint /api/loyumi/widget-session \
  --fallback-url /account/rewards

Stable process behavior for people and pipelines.

npx loyumi init \
  --environment "$LOYUMI_ENVIRONMENT_ID" \
  --non-interactive \
  --json

npx loyumi doctor --json
npx loyumi members get --external-id "$CUSTOMER_ID" --json

Know what failed before retrying.

1. 1

   Run npx loyumi doctor

   It validates the loaded config, API version, referenced credential, and connectivity. Use --offline to inspect local setup without an API request.

2. 2

   Show the effective config safely

   Use npx loyumi config show. Secret-like fields are recursively replaced with [REDACTED].

3. 3

   Ask the exact command

   Every command accepts --help. Use --version at the root before comparing behavior with these notes.

Upgrade deliberately, then run doctor again.

npm install --save-dev https://docs.loyumi.com/downloads/loyumi-cli-$APPROVED_LOYUMI_CLI_VERSION.tgz
npx loyumi --version
npx loyumi doctor

Read release notes, replace the pinned version only after the registry and notes agree, review configuration or command changes, then validate in Sandbox. Do not use an unreviewed @latest range in production CI.