Administrative CLI commands for HelloJohn — configuration, API key management, audit logs, email testing, and tenant operations.

hj admin

The hj admin command group provides administrative operations for managing your HelloJohn tenant configuration, API keys, audit logs, and operational tasks.

Commands

Command	Description
`hj admin config get`	View current tenant configuration
`hj admin config set`	Update tenant configuration
`hj admin config reset`	Reset a config key to its default
`hj admin api-keys list`	List API keys
`hj admin api-keys create`	Create a new API key
`hj admin api-keys revoke`	Revoke an API key
`hj admin audit`	Query audit log
`hj admin email test`	Send a test email
`hj admin email templates`	List and edit email templates
`hj admin rotate-encryption-key`	Re-encrypt fields with a new encryption key
`hj admin stats`	Show tenant usage statistics

hj admin config get

View the current tenant configuration:

hj admin config get

Output (subset):

{
  "session_access_token_ttl": 900,
  "session_refresh_token_ttl": 604800,
  "password_min_length": 8,
  "mfa_required": false,
  "allowed_origins": [
    "https://app.example.com",
    "https://www.example.com"
  ],
  "oauth_enabled_providers": ["google", "github"],
  "email_verification_required": true
}

Get a specific key:

hj admin config get allowed_origins

hj admin config set

Update a configuration value:

# Set a single value
hj admin config set password_min_length 12

# Set JSON value
hj admin config set allowed_origins '["https://app.example.com", "https://www.example.com"]'

# Interactive mode
hj admin config set --interactive

Commonly configured keys:

Key	Type	Description
`session_access_token_ttl`	number	Access token TTL in seconds
`session_refresh_token_ttl`	number	Refresh token TTL in seconds
`password_min_length`	number	Minimum password length
`password_require_uppercase`	boolean	Require uppercase character
`password_require_number`	boolean	Require numeric character
`mfa_required`	boolean	Enforce MFA for all users
`email_verification_required`	boolean	Require email verification before sign-in
`allowed_origins`	string[]	CORS allowed origins
`oauth_auto_link`	boolean	Auto-link OAuth accounts with matching email
`collect_ip_addresses`	boolean	Log IP addresses in sessions/audit

hj admin config reset

Reset a config key to its default value:

hj admin config reset password_min_length

hj admin api-keys list

List all API keys for the active tenant:

hj admin api-keys list

ID                    NAME              TYPE    LAST USED       CREATED
key_01HABCDEF001      Default           live    2 min ago       2024-01-15
key_01HABCDEF002      CI/CD             live    3 days ago      2024-03-01
key_01HABCDEF003      Dev               test    never           2024-03-20

hj admin api-keys create

Create a new API key:

hj admin api-keys create --name "CI/CD Pipeline" --type live

✅ API key created

Name:  CI/CD Pipeline
Type:  live
Key:   sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

⚠️  Store this key securely — it will not be shown again.

Flags:

Flag	Description
`--name`	Descriptive name for the key
`--type`	`live` for production, `test` for sandbox

hj admin api-keys revoke

Revoke an API key immediately:

hj admin api-keys revoke key_01HABCDEF002

All requests using this key will immediately receive 401 Unauthorized.

hj admin audit

Query the audit log:

# Last 50 events
hj admin audit

# Filter by event type
hj admin audit --event user.sign_in_failed

# Filter by user
hj admin audit --user usr_01HABCDEF123456

# Filter by time range
hj admin audit --since 24h

# Export as NDJSON
hj admin audit --since 30d --format ndjson > audit_export.ndjson

Flags:

Flag	Description
`--event <type>`	Filter by event type
`--user <id>`	Filter by user ID
`--ip <address>`	Filter by IP address
`--since <duration>`	Time range: `1h`, `24h`, `7d`, `30d`
`--limit <n>`	Results per page (default: 50, max: 500)
`--format table\|json\|ndjson`	Output format
`--output <file>`	Write to file instead of stdout

Example output:

TIME                 EVENT                    USER                    IP
2024-06-01 14:32     user.sign_in             usr_01HABCDEF123456     192.168.1.1
2024-06-01 14:30     user.sign_in_failed      —                       10.0.0.5
2024-06-01 14:28     admin.user_impersonated  usr_01HABCDEF123456     10.0.0.1

hj admin email test

Send a test email to verify your SMTP configuration:

hj admin email test --to you@example.com

✅ Test email sent to you@example.com
   Provider: Resend (smtp.resend.com:587)
   Delivery time: 1.2s

If it fails:

❌ Email delivery failed
   Error: authentication failed (535 5.7.8)
   Check HELLOJOHN_SMTP_PASSWORD

hj admin email templates

List and manage email templates:

# List templates
hj admin email templates list

# View a template
hj admin email templates get verification

# Edit a template (opens $EDITOR)
hj admin email templates edit verification

# Reset to default
hj admin email templates reset verification

Available templates: verification, magic_link, password_reset, mfa_otp, invitation, welcome.

hj admin rotate-encryption-key

Re-encrypt all sensitive fields with a new encryption key:

hj admin rotate-encryption-key \
  --new-key "$(openssl rand -base64 32)"

This is a long-running operation that re-encrypts OAuth client secrets, SMTP passwords, backup codes, and webhook secrets. HelloJohn remains operational during rotation.

Flags:

Flag	Description
`--new-key <key>`	New 32-byte base64-encoded key
`--dry-run`	Count fields to re-encrypt without executing

hj admin stats

View usage statistics for the active tenant:

hj admin stats

Tenant: Production (tnt_01HABCDEF654321)
Plan:   Pro

Users
  Total:          12,340
  Active (30d):    8,210
  New (30d):         345

Sessions
  Active:          4,521
  Created (30d):  28,400

Authentication
  Sign-ins (30d): 31,200
  Failed (30d):      890  (2.9%)
  MFA-protected:    6,100 users (49%)

hj admin

On this page