tpem

tpem is a Node.js/TypeScript CLI for managing temporary email addresses and mail on a cloudflare_temp_email compatible backend.

Install

Install from npm:

pnpm add -g @jingoz/tpem

Or build from this repository:

pnpm install
pnpm build

The npm package name is @jingoz/tpem and the CLI binary is tpem.

Configuration

tpem config set BASE_URL <your.domain.com>
tpem config set ADMIN_PWD <pwd>
tpem config set BASE_URL <your.domain.com> ADMIN_PWD <pwd>
tpem config set PROXY http://127.0.0.1:7890
tpem config set MAIL_WAIT 5 MAIL_RETRY 4
tpem config list [--json]
tpem config unset PROXY MAIL_WAIT MAIL_RETRY [--json]

BASE_URL is optional and defaults to the package's built-in service endpoint. ADMIN_PWD is required for commands that access the backend and is never echoed in normal output. PROXY is optional and supports http:// and https:// local proxy URLs for CLI network requests. MAIL_WAIT and MAIL_RETRY set the default --wait and --retry values for get-code and mail; command-line flags override the stored defaults for a single invocation. config list shows only stored values and renders ADMIN_PWD as ******. Proxy credentials are redacted in config list output.

Project-Scoped Config

Automation can isolate tpem from the user's global config by setting TPEM_CONFIG_FILE to an absolute config file path:

$env:TPEM_CONFIG_FILE = "D:\path\to\project\data\tpem\config.json"
tpem config set BASE_URL <url> ADMIN_PWD <pwd> PROXY <proxy> MAIL_WAIT 5 MAIL_RETRY 4 --json

When TPEM_CONFIG_FILE is set, every command that reads or writes config uses that file instead of %APPDATA%\tpem\config.json or the XDG config path. Relative paths are rejected with a usage error so subprocess callers do not depend on the current working directory.

Example subprocess flow:

$env:TPEM_CONFIG_FILE = "D:\path\to\project\data\tpem\config.json"
tpem create --random --json
tpem get-code [email protected] --wait 5 --retry 4 --json

create --random --json returns:

{
  "ok": true,
  "data": {
    "address": "[email protected]"
  }
}

get-code --json returns:

{
  "ok": true,
  "data": {
    "code": "123456"
  }
}

Commands

tpem addrs [--page <1>] [--limit <20>] [--json]
tpem mails [<[email protected]>] [--page <1>] [--limit <20>] [--json]
tpem get-code [<[email protected]>] [--latest] [--id <mail_id>] [--json] [--wait <0>] [--retry <0>]
tpem mail [<[email protected]>] [--latest] [--id <mail_id>] [--json] [--wait <0>] [--retry <0>]
tpem num [<[email protected]>] [--json]
tpem domains [--json]
tpem create [<[email protected]>] [--json]
tpem create --addr <[email protected]> [--json]
tpem create --name <name> [--domain <domain.com>] [--json]
tpem create --random [--domain <domain.com>] [--json]
tpem delete <[email protected]> [--json]
tpem delete --id <mail_id> [--json]
tpem clear <[email protected]> [--json]

get-code prints only the verification code or No verification code found. mail is currently a compatibility alias for get-code.

Destructive commands require re-entering the target value for confirmation.

JSON Output

Business commands support --json for script-friendly output. Successful JSON output is formatted and uses a stable envelope:

{
  "ok": true,
  "data": {
    "code": "123456"
  }
}

List commands that accept --page and --limit include request metadata:

{
  "ok": true,
  "data": [],
  "meta": {
    "page": 1,
    "limit": 20
  }
}

Errors in JSON mode are written to stderr, keep stdout empty, and preserve the normal exit code:

{
  "ok": false,
  "error": {
    "message": "Missing ADMIN_PWD. Run tpem config set ADMIN_PWD <pwd> first.",
    "code": "USAGE",
    "exitCode": 1
  }
}

Empty results are successful JSON results with stable empty values, such as [], { "code": null }, or { "entries": [] }. Destructive commands still require target confirmation in JSON mode; confirmation prompts are written outside stdout so stdout remains JSON-only.

Development

Use pnpm for all package management and verification:

pnpm install
pnpm typecheck
pnpm test
pnpm build

Local live-test environment variables are documented in .env.example. Live tests must be explicitly gated with TPEM_ENABLE_LIVE_TESTS=1.

Release Checklist

Before publishing:

pnpm release:check

Publish manually with npm after reviewing the dry-run package contents:

npm login
npm publish --access public