npm.io
0.2.1 • Published 23h agoCLI

@lanbox/cli

Licence
—
Version
0.2.1
Deps
1
Size
43 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

@lanbox/cli

npm version Node.js 22+ CI

Command-line interface for LanBox — local email infrastructure for developers.

Use @lanbox/cli from your terminal, shell scripts, or CI pipelines to generate virtual addresses, inspect captured emails, extract OTP verification codes, wait for magic links, and manage isolated test sessions without polling.

Prerequisites

The CLI communicates with a running LanBox instance. Start LanBox with Docker Compose:

docker compose up -d
Service Default Address
Web UI http://127.0.0.1:8025
REST API http://127.0.0.1:8025/api/v1
SMTP Server 127.0.0.1:1025
Virtual Domain lanbox.test

Installation & Execution

Run on demand (Recommended)
npx @lanbox/cli status
pnpm dlx @lanbox/cli status
Install globally
npm install -g @lanbox/cli
lanbox status

Requires Node.js >=22.0.0.

Quickstart

# Check runtime health
lanbox status

# Generate a virtual email address for testing
lanbox address signup

Output:

{
  "address": "signup-5ed4c0f5a812@lanbox.test"
}

Virtual Addresses: No mailbox creation is needed. Any address ending in @lanbox.test (or your configured domain) works immediately.

OTP Workflows

Extract 4–8 digit verification codes from plain text or HTML emails.

Wait for Incoming OTP (Recommended for Tests)

Blocks until the email arrives (up to --timeout milliseconds) and returns the extracted code:

lanbox wait-otp signup@lanbox.test --timeout 10000 --json

Output:

{
  "otp": "829441",
  "messageId": "8d73843e-89d2-4b31-8d5f-19e2ec2f3c04",
  "receivedAt": "2026-08-21T12:00:00.000Z",
  "subject": "Verify your account",
  "confidence": "high"
}
Extract OTP from Existing Email
lanbox otp user@lanbox.test --length 6

Magic Links

Extract action URLs from captured transactional emails.

# Wait for magic login link
lanbox wait-link user@lanbox.test --host app.example.test --path-includes /magic-login --timeout 10000 --json

Output:

{
  "link": "https://app.example.test/magic-login?token=d8f9a2bc1e3f",
  "messageId": "8d73843e-89d2-4b31-8d5f-19e2ec2f3c04",
  "receivedAt": "2026-08-21T12:00:00.000Z",
  "subject": "Sign in to your account"
}

Security Guarantee: LanBox ranks URLs by relevance but never fetches, opens, or executes extracted links.

Waiting for Messages

Wait for incoming emails matching specific filter criteria without polling:

# Wait for email by subject
lanbox wait user@lanbox.test --subject "Welcome" --timeout 10000

# Filter by sender and timestamp
lanbox wait user@lanbox.test --from billing@example.test --after 2026-08-21T12:00:00.000Z

Read the latest matching message already in the database:

lanbox latest user@lanbox.test --from auth@example.test

Isolated Test Sessions

Sessions prevent cross-test interference in parallel test suites by scoping messages to unique session IDs.

# 1. Create a session with a 15-minute TTL
lanbox session create --ttl 900 --prefix auth --json

# 2. Get session details
lanbox session get s_1234567890abcdef12345678 --json

# 3. Generate a new address for the session
lanbox session address s_1234567890abcdef12345678 --prefix reset

# 4. Delete the session and clear its matching messages
lanbox session delete s_1234567890abcdef12345678

Scripting & JSON Mode

Pass --json to output compact, machine-readable JSON to stdout. On error, structured JSON is written to stderr and a non-zero exit code (1) is returned:

OTP=$(lanbox wait-otp "$EMAIL" --timeout 10000 --json | jq -r .otp)
echo "Extracted OTP: $OTP"
Clearing Mailboxes
# Clear a single virtual inbox
lanbox clear user@lanbox.test

# Purge all messages and files (requires explicit confirmation flag)
lanbox clear-all --confirm

Remote & LAN Instances

Override API URL and virtual domain to connect to a LanBox instance running on your LAN or remote dev server:

lanbox --url http://192.168.1.20:8025/api/v1 status
lanbox address staging --domain mail.example.test

Help & Version

lanbox --help
lanbox -h
lanbox help
lanbox --version
lanbox -v

Connection Error Handling

When LanBox is stopped or unreachable, the CLI provides clear, actionable guidance:

LanBox is unreachable at http://127.0.0.1:8025.
Start it with: docker compose up -d

In --json mode:

{"error":{"code":"LANBOX_UNREACHABLE","message":"LanBox is unreachable at http://127.0.0.1:8025.\nStart it with: docker compose up -d"}}

Command Reference

Command Arguments Options Description
status — --json Check API, database, and SMTP health.
open — — Open the LanBox web UI in system browser.
address [prefix] --json Generate a collision-resistant address.
inboxes — --search, --limit, --offset, --json List virtual inboxes with message counts.
latest <address> --from, --subject, --after, --json Read the newest matching message.
wait <address> --from, --subject, --after, --timeout, --json Wait for a matching incoming email.
otp <address> --from, --subject, --after, --length, --json Extract OTP from stored email.
wait-otp <address> --from, --subject, --after, --timeout, --length, --json Wait for email and extract OTP.
link <address> --from, --subject, --after, --host, --path-includes, --json Extract magic link from stored email.
wait-link <address> --from, --subject, --after, --timeout, --host, --path-includes, --json Wait for email and extract magic link.
clear <address> --json Delete all deliveries for an inbox.
clear-all — --confirm, --json Purge all messages and files.
session create|get|address|delete --ttl, --prefix, --json Manage isolated test sessions.
Global Options
  • --url <api-url>: API base URL (default: http://127.0.0.1:8025/api/v1).
  • --domain <domain>: Virtual recipient domain (default: lanbox.test).
  • --json: Output compact JSON to stdout / stderr.
  • -h, --help: Display help information.
  • -v, --version: Display version information.

Links & Resources

License

No open-source license is currently selected. The repository owner must choose one before external reuse or redistribution.

Keywords

lanboxcliemail-testingsmtpotpmagic-linkse2e-testing