@everpaid/cli

Official Node.js 22 CLI for Everpaid. Telemetry is disabled; the CLI does not collect or transmit usage analytics.

npx @everpaid/cli auth login
npx @everpaid/cli env current
npx @everpaid/cli links list --status active
npx @everpaid/cli links create --title "Test link" --amount 10.00 --currency USD

Examples should use the simulated Sandbox. Every environment-bearing response says live, simulated, or regtest; env current prints the persisted selection. An OAuth authorization is bound to one exact environment. To add another, select it in Everpaid and run auth login again. env use <id> switches only among locally authorized environments.

Authentication and secrets

auth login uses RFC 8628 device authorization. It always prints the verification URL and user code, and opens the browser when interactive. --no-input is suitable for headless hosts. Access and rotating refresh tokens are stored in an application-data file, with no keychain or Secret Service dependency:

• macOS: ~/Library/Application Support/everpaid/auth.json
• Linux: $XDG_DATA_HOME/everpaid/auth.json, defaulting to ~/.local/share/everpaid/auth.json (relative XDG paths are ignored)
• Windows: %APPDATA%\everpaid\auth.json, defaulting to ~\AppData\Roaming\everpaid\auth.json

The file contains unencrypted OAuth credentials. Filesystem permissions protect it, not keychain encryption. Do not share, commit, or sync it to a shared directory. POSIX directories use 0700 and files use 0600; Windows uses a current-user-only ACL set through the built-in Windows PowerShell (no Credential Locker). A failed permission update fails closed. Writes use a private temporary file and atomic replacement; malformed files and symlink credential paths are rejected without printing their contents.

Non-secret current-environment metadata remains in the standard user config directory (EVERPAID_CONFIG_DIR overrides only that metadata, not credential storage). Existing keychain credentials are not migrated: before upgrading, log out with the old CLI (or revoke its grants in Everpaid), then log in again with this version. auth logout revokes the current grant before removing it; auth logout --all revokes all stored grants. Expired access tokens refresh once, and invalid/replayed refresh tokens require a new login.

Writes

OAuth writes are universally preview-first. The server returns an exact normalized preview plus a short-lived opaque token; the CLI shows that preview before sending the matching execution. Published links remain immutable.

• Interactive Sandbox/REGTEST: type yes.
• Interactive Live: type LIVE.
• Noninteractive Sandbox/REGTEST: pass --yes.
• Noninteractive Live: pass both --yes and --allow-live.

Use --idempotency-key <value> to make create/update retries deterministic. If omitted, the CLI generates one for that invocation. A timeout, signal, network failure, or ambiguous response is treated as failure; the CLI never claims the mutation succeeded. Inspect before retrying with a new key.

Output contract

Human-readable output is the default. --json writes one JSON object to stdout:

{"schemaVersion":"1","command":"env.current","data":{"environmentId":"…","environmentType":"simulated","current":true}}

Errors and previews go to stderr. JSON errors use the same envelope with command: "error" and {code,message} data. Collection cursors are opaque.

Stable exit codes:

• 0 success
• 1 API/internal failure or ambiguous server response
• 2 usage or confirmation required
• 3 authentication/credential-store/environment authorization required
• 4 permission or scope denied
• 5 resource not found
• 6 lifecycle/idempotency conflict
• 7 network failure
• 8 cancellation, signal, or timeout

Release and provenance

The package has its own lockfile and zero runtime dependencies. Before release:

npm ci
npm test
npm run smoke
npm publish --provenance --access public

Publish from a protected GitHub Actions environment with npm trusted publishing (OIDC), a clean signed version tag, Node 22, and the package lock unchanged. Verify the registry provenance attestation and smoke-test both npx @everpaid/cli --version and a clean global install on macOS, headless Linux without Secret Service, and Windows.