Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Helium CLI

The Helium CLI (helium-cli) is a comprehensive administrative tool that allows operators to:

  • Initialize system configurations with default values
  • Manage admin accounts (create, list, view, delete)
  • Validate configuration files before deployment
  • Interact with both PostgreSQL database and Redis cache

Installation

The CLI is built as part of the main Helium project. After building the project:

cargo build --release --bin helium-cli

The binary will be available at target/release/helium-cli.

Global Configuration

The CLI requires database and Redis connections to function. These can be configured via:

Environment Variables

export DATABASE_URL="postgresql://user:password@localhost/helium"
export REDIS_URL="redis://localhost:6379"

Command Line Arguments

helium-cli --database-url "postgresql://user:password@localhost/helium" \
           --redis-url "redis://localhost:6379" \
           <command>

Verbose Logging

Enable detailed logging for troubleshooting:

helium-cli --verbose <command>

Commands

Configuration Management

Initialize All Configurations

helium-cli init-config

This command initializes all system configurations with their default values. It:

  • Creates default configurations for all modules in the database
  • Updates Redis cache with the configurations
  • Handles the following configuration types:
    • Auth: Authentication and authorization settings
    • Admin JWT: JWT configuration for admin authentication
    • Telecom: Telecom service configurations
    • Shop: E-commerce and shop settings
    • Market: Affiliate and marketing configurations
    • Mailer: SMTP and email service settings

Example Output:

Initializing 6 configuration types...

Initializing Auth config... ✓ Success
Initializing Admin JWT config... ✓ Success
Initializing Telecom config... ✓ Success
Initializing Shop config... ✓ Success
Initializing Market/Affiliate config... ✓ Success
Initializing Mailer config... ✓ Success

Configuration initialization completed:
  ✓ Successful: 6

Use Cases:

  • Initial deployment setup
  • Resetting configurations to defaults
  • Disaster recovery scenarios

Validate Configuration Files

helium-cli validate-config --config-type <TYPE> <config-file.json>

Validates a JSON configuration file against the specified configuration schema.

Supported Configuration Types:

  • auth - Authentication configuration
  • admin-jwt / admin_jwt - Admin JWT configuration
  • telecom - Telecom service configuration
  • shop - Shop/e-commerce configuration
  • market / affiliate - Marketing/affiliate configuration
  • mailer - Email service configuration

Examples:

# Validate auth configuration
helium-cli validate-config --config-type auth auth-config.json

# Validate mailer configuration
helium-cli validate-config --config-type mailer smtp-config.json

Example Output:

✓ Configuration file is valid!
  File: auth-config.json
  Type: Auth
  Key: auth

Admin Account Management

List Admin Accounts

helium-cli admin list [--limit <N>] [--offset <N>]

Lists all admin accounts with pagination support.

Options:

  • --limit <N> - Number of results to return (default: 50)
  • --offset <N> - Number of results to skip (default: 0)

Example:

# List first 10 admin accounts
helium-cli admin list --limit 10

# List admin accounts with pagination
helium-cli admin list --limit 25 --offset 50

Example Output:

Found 3 admin account(s):

ID                                   Role                 Name                           Email                          Created At
------------------------------------ -------------------- ------------------------------ ------------------------------ --------------------
123e4567-e89b-12d3-a456-426614174000 Super Admin          System Administrator           admin@example.com              2024-01-15T10:30:00Z
234e5678-e89b-12d3-a456-426614174001 Customer Support     Support Team Lead              support@example.com            2024-01-16T14:20:00Z
345e6789-e89b-12d3-a456-426614174002 Moderator            Content Moderator              moderator@example.com          2024-01-17T09:45:00Z

Show Admin Account Details

helium-cli admin show <ADMIN_ID>

Displays detailed information about a specific admin account.

Example:

helium-cli admin show 123e4567-e89b-12d3-a456-426614174000

Example Output:

Admin Account Details:
  ID: 123e4567-e89b-12d3-a456-426614174000
  Name: System Administrator
  Role: Super Admin
  Email: admin@example.com
  Avatar: https://example.com/avatar.jpg
  Created At: 2024-01-15T10:30:00Z

Create Admin Account

helium-cli admin create --name <NAME> --role <ROLE> [--email <EMAIL>] [--avatar <AVATAR_URL>]

Creates a new admin account with the specified details.

Required Options:

  • --name <NAME> - Display name for the admin
  • --role <ROLE> - Admin role (see roles below)

Optional Options:

  • --email <EMAIL> - Admin email address
  • --avatar <AVATAR_URL> - URL to admin avatar image

Available Roles:

  • super_admin / superadmin / super-admin - Full system access
  • moderator - Content moderation privileges
  • customer_support / customersupport / customer-support - Customer service access
  • support_bot / supportbot / support-bot - Automated support system access

Examples:

# Create super admin
helium-cli admin create \
  --name "System Administrator" \
  --role super_admin \
  --email "admin@example.com"

# Create customer support account
helium-cli admin create \
  --name "Support Agent" \
  --role customer_support \
  --email "support@example.com" \
  --avatar "https://example.com/avatars/support.jpg"

# Create moderator (minimal info)
helium-cli admin create \
  --name "Content Moderator" \
  --role moderator

Example Output:

Successfully created admin account:
  ID: 456e7890-e89b-12d3-a456-426614174003
  Name: System Administrator
  Role: Super Admin
  Email: admin@example.com
  Avatar: N/A

Delete Admin Account

helium-cli admin delete <ADMIN_ID> [--yes]

Deletes an admin account after confirmation.

Options:

  • --yes - Skip confirmation prompt (use with caution)

Examples:

# Delete with confirmation prompt
helium-cli admin delete 123e4567-e89b-12d3-a456-426614174000

# Delete without confirmation (automated scripts)
helium-cli admin delete 123e4567-e89b-12d3-a456-426614174000 --yes

Example Interactive Flow:

Admin account to delete:
  ID: 123e4567-e89b-12d3-a456-426614174000
  Name: Old Administrator
  Role: Super Admin
  Email: old-admin@example.com

Are you sure you want to delete this admin account? [y/N]: y
Successfully deleted admin account: 123e4567-e89b-12d3-a456-426614174000

Common Use Cases

Initial Deployment

  1. Set up environment variables:

    export DATABASE_URL="postgresql://helium:password@localhost/helium"
export REDIS_URL="redis://localhost:6379"

  2. Initialize system configurations:

    helium-cli init-config

  3. Create initial super admin:

    helium-cli admin create \
  --name "System Administrator" \
  --role super_admin \
  --email "admin@yourcompany.com"

Configuration Management Workflow

  1. Prepare configuration file: Create a JSON file with your custom configuration.

  2. Validate before deployment:

    helium-cli validate-config --config-type auth ./configs/auth-config.json

  3. Deploy configuration: Use the web interface or API to upload the validated configuration.

Admin Account Maintenance

  1. Regular audit of admin accounts:

    helium-cli admin list --limit 100

  2. Create specialized support accounts:

    # Customer support team
helium-cli admin create --name "Support Team A" --role customer_support

# Content moderation team
helium-cli admin create --name "Moderator Team B" --role moderator

  3. Remove inactive accounts:

    helium-cli admin delete <inactive-admin-id>

Error Handling

The CLI provides comprehensive error messages and logging:

  • Database Connection Issues: Check DATABASE_URL and database availability
  • Redis Connection Issues: Verify REDIS_URL and Redis service status
  • Configuration Validation Errors: Review JSON syntax and required fields
  • Admin Role Errors: Ensure role names match supported values exactly

Security Considerations

  1. Environment Variables: Use secure methods to set database credentials
  2. Admin Creation: Be selective with super_admin role assignments
  3. Account Deletion: Always verify admin identity before deletion
  4. Logging: Be aware that verbose mode may log sensitive information

Troubleshooting

Common Issues

“DATABASE_URL must be provided”

  • Set the DATABASE_URL environment variable or use --database-url flag

“Failed to connect to database”

  • Verify PostgreSQL is running and accessible
  • Check connection string format and credentials
  • Ensure the database exists

“Invalid admin role”

  • Use exact role names: super_admin, moderator, customer_support, support_bot
  • Role names are case-insensitive but must match supported variants

“Configuration validation failed”

  • Check JSON syntax with a JSON validator
  • Ensure all required fields are present
  • Verify field types match expected schema

Getting Help

Use the built-in help system:

# General help
helium-cli --help

# Command-specific help
helium-cli admin --help
helium-cli admin create --help

Integration with Deployment Scripts

The CLI is designed to work well in automated deployment scenarios:

#!/bin/bash
set -e

# Set environment
export DATABASE_URL="$HELIUM_DB_URL"
export REDIS_URL="$HELIUM_REDIS_URL"

# Initialize configurations
echo "Initializing Helium configurations..."
helium-cli init-config

# Create admin account if it doesn't exist
echo "Creating admin account..."
helium-cli admin create \
  --name "$ADMIN_NAME" \
  --role super_admin \
  --email "$ADMIN_EMAIL" || true

echo "Deployment initialization complete!"

This CLI tool is essential for proper Helium deployment and ongoing operational management. Use it as part of your deployment automation and regular maintenance procedures.