Manage HelloJohn users, tenants, API keys, and webhooks from the command line with hjctl.

hjctl CLI

hjctl is the official command-line interface for HelloJohn. Use it to manage users, tenants, API keys, and more — from your terminal, CI/CD pipelines, and scripts.

Installation

macOS (Homebrew)

brew install hellojohn/tap/hjctl

Linux

# Download binary
curl -fsSL https://hellojohn.dev/install/hjctl.sh | bash

# Or download manually
HJCTL_VERSION=1.2.3
curl -fsSL "https://github.com/hellojohn/hjctl/releases/download/v${HJCTL_VERSION}/hjctl-linux-amd64.tar.gz" | tar xz
sudo mv hjctl /usr/local/bin/

Windows

# Via Scoop
scoop bucket add hellojohn https://github.com/hellojohn/scoop-bucket
scoop install hjctl

# Or download from GitHub releases

Verify installation

hjctl version
# hjctl v1.2.3 (linux/amd64)

Authentication

hjctl auth login
# Opens browser for authentication
# Or: hjctl auth login --api-key sk_live_...

Using an API key (CI/CD)

export HJ_API_KEY=sk_live_...
hjctl users list  # uses HJ_API_KEY automatically

Or use the --api-key flag:

hjctl --api-key sk_live_... users list

Configure a profile

hjctl config set api-key sk_live_...
hjctl config set api-url https://auth.yourdomain.com  # for self-hosted

# Use named profiles
hjctl config set --profile staging api-key sk_test_...
hjctl --profile staging users list

Config is stored at ~/.config/hjctl/config.yaml.

Users

# List users
hjctl users list
hjctl users list --tenant tnt_01H...
hjctl users list --limit 100 --format json

# Get a user
hjctl users get usr_01H...
hjctl users get --email alice@example.com

# Create a user
hjctl users create \
  --email alice@example.com \
  --password strongpassword \
  --display-name "Alice" \
  --tenant tnt_01H... \
  --role member

# Update a user
hjctl users update usr_01H... --role admin
hjctl users update usr_01H... --display-name "Alice Smith"

# Disable / enable a user
hjctl users disable usr_01H...
hjctl users enable usr_01H...

# Delete a user
hjctl users delete usr_01H...
hjctl users delete usr_01H... --confirm  # skip confirmation prompt

# Reset a user's password
hjctl users reset-password usr_01H...
# Sends a password reset email

# Force a new password directly
hjctl users set-password usr_01H... --password newstrongpassword

# Revoke all sessions
hjctl users revoke-sessions usr_01H...

# List a user's sessions
hjctl users sessions usr_01H...

Tenants

# List tenants
hjctl tenants list
hjctl tenants list --format json

# Get a tenant
hjctl tenants get tnt_01H...
hjctl tenants get --slug acme-corp

# Create a tenant
hjctl tenants create --name "Acme Corp" --slug acme-corp

# Update a tenant
hjctl tenants update tnt_01H... --name "Acme Corporation"

# Delete a tenant
hjctl tenants delete tnt_01H...

# View tenant stats
hjctl tenants stats tnt_01H...
# Users: 142
# Active sessions: 38
# Organizations: 7

API keys

# List API keys
hjctl api-keys list
hjctl api-keys list --tenant tnt_01H...

# Create an API key
hjctl api-keys create \
  --name "CI/CD Pipeline" \
  --scopes users:read,tenants:read \
  --expires 2025-01-01

# The secret is displayed once — copy it immediately
# Key ID: key_01H...
# Secret: sk_live_... (shown once)

# Rotate an API key
hjctl api-keys rotate key_01H...

# Revoke an API key
hjctl api-keys revoke key_01H...

Organizations

# List organizations in a tenant
hjctl orgs list --tenant tnt_01H...

# Create an organization
hjctl orgs create --tenant tnt_01H... --name "Engineering" --slug engineering

# Add a member
hjctl orgs add-member org_01H... --user usr_01H... --role member

# Remove a member
hjctl orgs remove-member org_01H... --user usr_01H...

# List members
hjctl orgs members org_01H...

Webhooks

# List webhooks
hjctl webhooks list

# Create a webhook
hjctl webhooks create \
  --url https://yourapp.com/webhooks/hellojohn \
  --events user.created,user.login,mfa.enrolled \
  --secret my-signing-secret

# Test a webhook (sends a test event)
hjctl webhooks test wh_01H...

# Delete a webhook
hjctl webhooks delete wh_01H...

# View recent deliveries
hjctl webhooks deliveries wh_01H...
hjctl webhooks deliveries wh_01H... --status failed

Audit logs

# View recent audit logs
hjctl audit-logs list
hjctl audit-logs list --type user.login_failed
hjctl audit-logs list --from 2024-01-01 --to 2024-01-31

# Filter by actor
hjctl audit-logs list --actor usr_01H...

# Filter by IP
hjctl audit-logs list --ip 203.0.113.42

# Export to file
hjctl audit-logs export --format csv --from 2024-01-01 -o audit_jan.csv
hjctl audit-logs export --format ndjson --from 2024-01-01 -o audit_jan.ndjson

Server management (self-hosted)

# Run database migrations
hjctl migrate

# Check migration status
hjctl migrate status

# Seed the first admin
hjctl admin seed --email admin@yourdomain.com --password strongpassword

# Health check
hjctl health
# ✓ API: https://auth.yourdomain.com (v1.2.3)
# ✓ Database: connected (pg 16.1)
# ✓ Redis: connected
# ✓ SMTP: connected

# View server config (redacts secrets)
hjctl config show-server

Local development

# Forward localhost webhook events to your local server
hjctl webhooks forward --port 3001
# Forwarding webhook events → http://localhost:3001/webhooks/hellojohn
# Use Ctrl+C to stop

# Start a local HelloJohn instance (uses Docker)
hjctl dev start
hjctl dev stop
hjctl dev status

Output formats

All commands support --format flag:

hjctl users list --format table   # default — human-readable table
hjctl users list --format json    # JSON array
hjctl users list --format yaml    # YAML
hjctl users list --format csv     # CSV (for applicable commands)

Use JSON output for scripting:

# Get a user's ID by email
USER_ID=$(hjctl users get --email alice@example.com --format json | jq -r '.id')
echo "User ID: $USER_ID"

# Disable all users in a tenant
hjctl users list --tenant tnt_01H... --format json | \
  jq -r '.[].id' | \
  xargs -I{} hjctl users disable {}

Shell completion

# bash
hjctl completion bash > /etc/bash_completion.d/hjctl

# zsh
hjctl completion zsh > "${fpath[1]}/_hjctl"

# fish
hjctl completion fish > ~/.config/fish/completions/hjctl.fish

# PowerShell
hjctl completion powershell | Out-String | Invoke-Expression

hjctl CLI

On this page