Skip to main content

Appendix B: CLI Command Reference

Installation

# Install globally
dart pub global activate hypermodern_cli

# Verify installation
hypermodern --version

Global Options

All commands support these global options:

  • --help, -h: Show help information
  • --verbose, -v: Enable verbose output
  • --quiet, -q: Suppress non-essential output
  • --config, -c <path>: Use custom configuration file
  • --no-color: Disable colored output

Project Commands

create

Create a new Hypermodern project.

hypermodern create <project_name> [options]

Options:

  • --template, -t <template>: Project template (default: basic)
    • basic: Basic server project
    • api: REST API project
    • chat: Real-time chat application
    • microservice: Microservice template
  • --description, -d <description>: Project description
  • --author, -a <author>: Project author
  • --license, -l <license>: Project license (default: MIT)
  • --git: Initialize git repository
  • --install-deps: Install dependencies after creation

Examples:

# Create basic project
hypermodern create my_app

# Create API project with custom options
hypermodern create my_api --template api --author "John Doe" --git

# Create chat application
hypermodern create chat_app --template chat --install-deps

init

Initialize Hypermodern in an existing directory.

hypermodern init [options]

Options:

  • --force, -f: Overwrite existing files
  • --template, -t <template>: Project template
  • --minimal: Create minimal configuration

Examples:

# Initialize in current directory
hypermodern init

# Force initialization with API template
hypermodern init --template api --force

Code Generation Commands

generate

Generate code from schemas.

hypermodern generate [target] [options]

Targets:

  • all (default): Generate all code
  • models: Generate model classes only
  • client: Generate client code only
  • server: Generate server code only
  • docs: Generate API documentation

Options:

  • --output, -o <directory>: Output directory (default: lib/generated)
  • --watch, -w: Watch for schema changes
  • --clean: Clean output directory before generation
  • --format: Format generated code
  • --validate: Validate schemas before generation

Examples:

# Generate all code
hypermodern generate

# Generate only models with watch mode
hypermodern generate models --watch

# Generate client code to custom directory
hypermodern generate client --output lib/api_client

generate:job

Generate a new scheduled job class with optional templates.

hypermodern generate:job <job_name> [options]

Options:

  • --template, -t <template>: Job template to use
  • --description, -d <description>: Job description for documentation
  • --parameters, -p <params>: Comma-separated list of parameter names
  • --output, -o <directory>: Output directory (default: lib/src)
  • --list-templates: List available job templates
  • --verbose, -v: Enable verbose output

Available Templates:

  • basic: Simple job template with minimal structure
  • email: Email sending job with template support
  • cleanup: Data cleanup job with configurable retention
  • report: Report generation job with file output
  • api: External API call job with retry logic
  • batch: Batch processing job for large datasets
  • notification: Push notification job with multiple providers

Generated Files:

  • <output>/jobs/<job_name>_job.dart: Main job implementation
  • <output>/test/jobs/<job_name>_job_test.dart: Unit tests
  • <output>/jobs/job_registry.dart: Registration helper

Examples:

# Generate basic job
hypermodern generate:job send_welcome_email

# Generate with description and parameters
hypermodern generate:job send_welcome_email \
  --description "Send welcome email to new users" \
  --parameters "user_id,email,name"

# Generate using email template
hypermodern generate:job newsletter_sender \
  --template email \
  --description "Send newsletter to subscribers"

# Generate cleanup job with parameters
hypermodern generate:job old_data_cleanup \
  --template cleanup \
  --parameters "table_name,retention_days" \
  --output lib/jobs

# List available templates
hypermodern generate:job --list-templates

# Generate API integration job
hypermodern generate:job webhook_sender \
  --template api \
  --description "Send webhook notifications" \
  --verbose

Job Registration: After generating a job, register it in your application:

// In your application startup
final jobRegistry = JobRegistry();
final scheduler = JobScheduler(registry: jobRegistry);

// Register generated jobs
JobRegistryHelper.registerAllJobs(jobRegistry);

// Or register individually
jobRegistry.register('send_welcome_email', () => SendWelcomeEmailJob());

// Start the scheduler
scheduler.start();

Development Commands

serve

Start the development server with hot reload.

hypermodern serve [options]

Options:

  • --http-port <port>: HTTP server port (default: 8080)
  • --ws-port <port>: WebSocket server port (default: 8082)
  • --tcp-port <port>: TCP server port (default: 8081)
  • --bind-address <address>: Bind address (default: 0.0.0.0)
  • --no-watch: Disable file watching
  • --no-reload: Disable hot reload
  • --config <file>: Configuration file
  • --env <environment>: Environment (development, staging, production)

Examples:

# Start development server
hypermodern serve

# Start with custom ports
hypermodern serve --http-port 3000 --ws-port 3001

# Start without hot reload
hypermodern serve --no-reload

build

Build the project for production.

hypermodern build [options]

Options:

  • --output, -o <directory>: Output directory (default: build)
  • --minify: Minify output
  • --tree-shake: Enable tree shaking
  • --source-maps: Generate source maps
  • --docker: Generate Docker files
  • --env <environment>: Target environment
  • --target <target>: Build target (exe, js, docker)

Examples:

# Basic production build
hypermodern build

# Build with Docker files
hypermodern build --docker --minify

# Build to custom directory
hypermodern build --output dist --tree-shake

Module Commands

module install

Install a module.

hypermodern module install <module> [options]

Options:

  • --version, -v <version>: Specific version to install
  • --dev: Install as development dependency
  • --global, -g: Install globally
  • --force, -f: Force installation
  • --no-deps: Don't install dependencies

Examples:

# Install latest version
hypermodern module install hypermodern_auth

# Install specific version
hypermodern module install hypermodern_auth --version 1.2.0

# Install from local path
hypermodern module install ./my_module

module uninstall

Uninstall a module.

hypermodern module uninstall <module> [options]

Options:

  • --force, -f: Force uninstallation
  • --keep-data: Keep module data

Examples:

# Uninstall module
hypermodern module uninstall hypermodern_auth

# Force uninstall keeping data
hypermodern module uninstall hypermodern_auth --force --keep-data

module list

List installed modules.

hypermodern module list [options]

Options:

  • --global, -g: List global modules
  • --outdated: Show outdated modules
  • --json: Output as JSON

Examples:

# List local modules
hypermodern module list

# List global modules
hypermodern module list --global

# Show outdated modules
hypermodern module list --outdated

module create

Create a new module.

hypermodern module create <module_name> [options]

Options:

  • --template, -t <template>: Module template
  • --description, -d <description>: Module description
  • --author, -a <author>: Module author
  • --license, -l <license>: Module license

Examples:

# Create basic module
hypermodern module create my_module

# Create with custom options
hypermodern module create my_auth --template auth --author "John Doe"

module validate

Validate a module.

hypermodern module validate <path> [options]

Options:

  • --strict: Enable strict validation
  • --fix: Automatically fix issues
  • --report <format>: Report format (text, json, html)

Examples:

# Validate current module
hypermodern module validate .

# Validate with strict mode
hypermodern module validate ./my_module --strict

module publish

Publish a module to the registry.

hypermodern module publish [path] [options]

Options:

  • --registry <url>: Registry URL
  • --token <token>: Authentication token
  • --dry-run: Perform dry run
  • --force: Force publish

Examples:

# Publish current module
hypermodern module publish

# Dry run publish
hypermodern module publish --dry-run

Schema Commands

schema validate

Validate schema files.

hypermodern schema validate [files...] [options]

Options:

  • --strict: Enable strict validation
  • --format <format>: Output format (text, json)
  • --fix: Automatically fix issues

Examples:

# Validate all schemas
hypermodern schema validate

# Validate specific files
hypermodern schema validate schemas/models.json schemas/endpoints.json

# Strict validation with fixes
hypermodern schema validate --strict --fix

schema merge

Merge multiple schema files.

hypermodern schema merge <files...> [options]

Options:

  • --output, -o <file>: Output file
  • --format <format>: Output format (json, yaml)
  • --validate: Validate merged schema

Examples:

# Merge schemas to stdout
hypermodern schema merge schemas/*.json

# Merge to file
hypermodern schema merge schemas/*.json --output merged.json

schema diff

Compare two schema files.

hypermodern schema diff <old_schema> <new_schema> [options]

Options:

  • --format <format>: Output format (text, json, html)
  • --ignore-order: Ignore field order
  • --breaking-only: Show only breaking changes

Examples:

# Compare schemas
hypermodern schema diff old.json new.json

# Show only breaking changes
hypermodern schema diff old.json new.json --breaking-only

Database Commands

db migrate

Run database migrations.

hypermodern db migrate [options]

Options:

  • --target <migration>: Target migration
  • --dry-run: Show what would be migrated
  • --force: Force migration
  • --rollback <steps>: Rollback steps

Examples:

# Run all pending migrations
hypermodern db migrate

# Dry run migrations
hypermodern db migrate --dry-run

# Rollback last migration
hypermodern db migrate --rollback 1

db rollback

Rollback database migrations.

hypermodern db rollback <migration_id> [options]

Options:

  • --dry-run: Show what would be rolled back
  • --force: Force rollback

Examples:

# Rollback specific migration
hypermodern db rollback 001_create_users

# Dry run rollback
hypermodern db rollback 001_create_users --dry-run

db status

Show migration status.

hypermodern db status [options]

Options:

  • --format <format>: Output format (table, json)
  • --pending: Show only pending migrations

Examples:

# Show migration status
hypermodern db status

# Show only pending migrations
hypermodern db status --pending

db seed

Run database seeders.

hypermodern db seed [seeders...] [options]

Options:

  • --env <environment>: Environment
  • --force: Force seeding

Examples:

# Run all seeders
hypermodern db seed

# Run specific seeders
hypermodern db seed users posts

db reset

Reset database.

hypermodern db reset [options]

Options:

  • --force: Force reset without confirmation
  • --seed: Run seeders after reset

Examples:

# Reset database
hypermodern db reset

# Reset and seed
hypermodern db reset --seed

Credentials Management Commands

credentials store

Store a credential securely.

hypermodern credentials store <key> [value] [options]

Arguments:

  • <key>: Credential key/identifier
  • [value]: Credential value (prompts securely if not provided)

Options:

  • --expires-in <duration>: Set expiration time (e.g., 30d, 1h)
  • --metadata <json>: Additional metadata as JSON

Examples:

# Store credential with prompt
hypermodern credentials store stripe_key

# Store credential with value
hypermodern credentials store stripe_key sk_test_123456789

# Store with expiration
hypermodern credentials store temp_token abc123 --expires-in 1h

# Store with metadata
hypermodern credentials store api_key xyz789 --metadata '{"source": "manual"}'

credentials get

Retrieve a credential value.

hypermodern credentials get <key>

Arguments:

  • <key>: Credential key to retrieve

Examples:

# Get credential value
hypermodern credentials get stripe_key

# Use in scripts
API_KEY=$(hypermodern credentials get api_key)

credentials list

List all stored credential keys.

hypermodern credentials list [options]

Options:

  • --format <format>: Output format (table, json, plain)
  • --show-metadata: Include metadata in output

Examples:

# List all credentials
hypermodern credentials list

# List with metadata
hypermodern credentials list --show-metadata

# JSON output
hypermodern credentials list --format json

credentials remove

Remove a stored credential.

hypermodern credentials remove <key> [options]

Arguments:

  • <key>: Credential key to remove

Options:

  • --force, -f: Skip confirmation prompt

Examples:

# Remove credential with confirmation
hypermodern credentials remove old_api_key

# Force remove without confirmation
hypermodern credentials remove old_api_key --force

credentials clear

Clear all stored credentials.

hypermodern credentials clear [options]

Options:

  • --force, -f: Skip confirmation prompt

Examples:

# Clear all credentials with confirmation
hypermodern credentials clear

# Force clear without confirmation
hypermodern credentials clear --force

credentials db

Store database credentials interactively.

hypermodern credentials db [name] [options]

Arguments:

  • [name]: Optional database name for multiple databases

Options:

  • --host <host>: Database host
  • --port <port>: Database port
  • --database <database>: Database name
  • --username <username>: Database username
  • --password <password>: Database password (prompts if not provided)

Examples:

# Store default database credentials
hypermodern credentials db

# Store named database credentials
hypermodern credentials db production

# Store with command-line options
hypermodern credentials db staging \
  --host staging-db.company.com \
  --port 5432 \
  --database staging_app \
  --username app_user

credentials aws

Store AWS credentials interactively.

hypermodern credentials aws [profile] [options]

Arguments:

  • [profile]: Optional AWS profile name

Options:

  • --access-key-id <key>: AWS Access Key ID
  • --secret-access-key <secret>: AWS Secret Access Key (prompts if not provided)
  • --region <region>: AWS region (default: us-east-1)
  • --session-token <token>: AWS session token (optional)

Examples:

# Store default AWS credentials
hypermodern credentials aws

# Store named profile credentials
hypermodern credentials aws production

# Store with command-line options
hypermodern credentials aws staging \
  --access-key-id AKIASTAGING123 \
  --region us-west-2

credentials import

Import credentials from an environment file.

hypermodern credentials import <file> [options]

Arguments:

  • <file>: Environment file to import from

Options:

  • --format <format>: File format (env, json, yaml)
  • --prefix <prefix>: Only import variables with prefix
  • --dry-run: Show what would be imported without storing
  • --overwrite: Overwrite existing credentials

Examples:

# Import from .env file
hypermodern credentials import .env.production

# Import with prefix filter
hypermodern credentials import .env --prefix DATABASE_

# Dry run import
hypermodern credentials import .env.staging --dry-run

# Import JSON file
hypermodern credentials import config.json --format json

credentials export

Export credentials in environment variable format.

hypermodern credentials export [options]

Options:

  • --format <format>: Output format (env, json, yaml)
  • --prefix <prefix>: Add prefix to variable names
  • --output, -o <file>: Write to file instead of stdout
  • --template <template>: Use export template (docker, k8s, github-actions)

Examples:

# Export as environment variables
hypermodern credentials export

# Export to file
hypermodern credentials export --output .env.local

# Export as JSON
hypermodern credentials export --format json

# Export for Docker
hypermodern credentials export --template docker

# Export for Kubernetes
hypermodern credentials export --template k8s --output k8s-secrets.yaml

Export Templates:

Docker format:

hypermodern credentials export --template docker
# Output:
# ENV STRIPE_KEY=sk_test_123
# ENV DATABASE_URL=postgresql://...

Kubernetes format:

hypermodern credentials export --template k8s
# Output:
# apiVersion: v1
# kind: Secret
# metadata:
#   name: app-credentials
# data:
#   stripe-key: <base64-encoded>

GitHub Actions format:

hypermodern credentials export --template github-actions
# Output:
# STRIPE_KEY: ${{ secrets.STRIPE_KEY }}
# DATABASE_URL: ${{ secrets.DATABASE_URL }}

Job Management Commands

job list

List scheduled jobs and their status.

hypermodern job list [options]

Options:

  • --status <status>: Filter by job status (pending, running, completed, failed, cancelled)
  • --limit <number>: Limit number of results (default: 50)
  • --format <format>: Output format (table, json, csv)
  • --verbose, -v: Show detailed information

Examples:

# List all jobs
hypermodern job list

# List only failed jobs
hypermodern job list --status failed

# List with detailed information
hypermodern job list --verbose --format json

job cancel

Cancel a scheduled job.

hypermodern job cancel <job_id> [options]

Options:

  • --force, -f: Force cancellation
  • --reason <reason>: Cancellation reason

Examples:

# Cancel a job
hypermodern job cancel 12345

# Force cancel with reason
hypermodern job cancel 12345 --force --reason "No longer needed"

job retry

Retry a failed job.

hypermodern job retry <job_id> [options]

Options:

  • --delay <duration>: Delay before retry (e.g., 5m, 1h)
  • --max-retries <number>: Override max retry count

Examples:

# Retry immediately
hypermodern job retry 12345

# Retry with delay
hypermodern job retry 12345 --delay 10m

job schedule

Schedule a job for execution.

hypermodern job schedule <job_identifier> [options]

Options:

  • --at <datetime>: Schedule for specific time (ISO 8601 format)
  • --in <duration>: Schedule after duration (e.g., 5m, 1h, 2d)
  • --params <json>: Job parameters as JSON
  • --description <description>: Job description
  • --max-retries <number>: Maximum retry attempts
  • --retry-delay <duration>: Delay between retries

Examples:

# Schedule job to run in 1 hour
hypermodern job schedule send_welcome_email \
  --in 1h \
  --params '{"email": "user@example.com", "name": "John Doe"}'

# Schedule for specific time
hypermodern job schedule generate_report \
  --at "2024-12-31T23:59:00Z" \
  --params '{"report_type": "yearly"}' \
  --description "End of year report"

# Schedule with retry configuration
hypermodern job schedule api_sync \
  --in 5m \
  --max-retries 5 \
  --retry-delay 2m \
  --params '{"endpoint": "/api/sync"}'

job stats

Show job execution statistics.

hypermodern job stats [options]

Options:

  • --period <period>: Time period (1h, 24h, 7d, 30d)
  • --job-type <identifier>: Filter by job type
  • --format <format>: Output format (table, json)

Examples:

# Show overall statistics
hypermodern job stats

# Show statistics for last 24 hours
hypermodern job stats --period 24h

# Show statistics for specific job type
hypermodern job stats --job-type send_welcome_email

Testing Commands

test

Run tests.

hypermodern test [files...] [options]

Options:

  • --unit: Run unit tests only
  • --integration: Run integration tests only
  • --coverage: Generate coverage report
  • --watch, -w: Watch mode
  • --reporter <reporter>: Test reporter
  • --timeout <seconds>: Test timeout

Examples:

# Run all tests
hypermodern test

# Run unit tests with coverage
hypermodern test --unit --coverage

# Watch mode
hypermodern test --watch

Utility Commands

lint

Lint code.

hypermodern lint [files...] [options]

Options:

  • --fix: Automatically fix issues
  • --rules <file>: Custom rules file
  • --format <format>: Output format

Examples:

# Lint all files
hypermodern lint

# Lint with auto-fix
hypermodern lint --fix

format

Format code.

hypermodern format [files...] [options]

Options:

  • --check: Check if files are formatted
  • --diff: Show formatting differences

Examples:

# Format all files
hypermodern format

# Check formatting
hypermodern format --check

analyze

Analyze code quality.

hypermodern analyze [options]

Options:

  • --output, -o <file>: Output file
  • --format <format>: Output format
  • --threshold <score>: Quality threshold

Examples:

# Analyze code
hypermodern analyze

# Analyze with custom threshold
hypermodern analyze --threshold 8.0

docs

Generate documentation.

hypermodern docs [options]

Options:

  • --output, -o <directory>: Output directory
  • --format <format>: Documentation format (html, markdown)
  • --include-private: Include private APIs
  • --serve: Serve documentation locally

Examples:

# Generate documentation
hypermodern docs

# Generate and serve
hypermodern docs --serve

# Generate markdown docs
hypermodern docs --format markdown --output docs/

Configuration Commands

config

Manage configuration.

hypermodern config <command> [options]

Subcommands:

  • get <key>: Get configuration value
  • set <key> <value>: Set configuration value
  • unset <key>: Remove configuration value
  • list: List all configuration
  • reset: Reset to defaults

Examples:

# Get configuration value
hypermodern config get server.http_port

# Set configuration value
hypermodern config set server.http_port 3000

# List all configuration
hypermodern config list

Environment Variables

The CLI respects these environment variables:

  • HYPERMODERN_CONFIG: Path to configuration file
  • HYPERMODERN_LOG_LEVEL: Log level (debug, info, warn, error)
  • HYPERMODERN_NO_COLOR: Disable colored output
  • HYPERMODERN_REGISTRY_URL: Module registry URL
  • HYPERMODERN_REGISTRY_TOKEN: Registry authentication token
  • HYPERMODERN_JOB_SCHEDULER_INTERVAL: Job scheduler execution interval (default: 30s)
  • HYPERMODERN_JOB_MAX_TASKS_PER_CYCLE: Maximum jobs per execution cycle (default: 50)
  • HYPERMODERN_JOB_AUTO_START: Auto-start job scheduler (default: true)
  • HYPERMODERN_ENCRYPTION_KEY: Encryption key for credentials storage
  • HYPERMODERN_CREDENTIALS_PATH: Custom path for credentials storage (default: .hypermodern/credentials.json)

Configuration File

The CLI looks for configuration in these locations (in order):

  1. hypermodern.yaml in current directory
  2. .hypermodern/config.yaml in current directory
  3. ~/.hypermodern/config.yaml in home directory
  4. /etc/hypermodern/config.yaml system-wide

Example configuration file:

# hypermodern.yaml
project:
  name: "my_project"
  version: "1.0.0"

server:
  http_port: 8080
  ws_port: 8082
  tcp_port: 8081

database:
  url: "postgresql://localhost:5432/myapp"

modules:
  directory: "modules"
  registry_url: "https://registry.hypermodern.dev"

jobs:
  auto_start: true
  execution_interval: "30s"
  max_tasks_per_cycle: 50
  default_max_retries: 3
  default_retry_delay: "5m"

credentials:
  storage_path: ".hypermodern/credentials.json"
  encryption_key_env: "HYPERMODERN_ENCRYPTION_KEY"
  auto_fallback_env: true

build:
  output_directory: "build"
  minify: true
  tree_shake: true

testing:
  coverage_threshold: 80
  timeout: 30

logging:
  level: "info"
  format: "json"

Exit Codes

The CLI uses these exit codes:

  • 0: Success
  • 1: General error
  • 2: Invalid arguments
  • 3: Configuration error
  • 4: Network error
  • 5: File system error
  • 6: Validation error
  • 7: Build error
  • 8: Test failure

Shell Completion

Enable shell completion for all commands including job generation:

# Bash
hypermodern completion bash >> ~/.bashrc

# Zsh
hypermodern completion zsh >> ~/.zshrc

# Fish
hypermodern completion fish >> ~/.config/fish/completions/hypermodern.fish

Completion Features:

  • Command names and subcommands
  • Option names and values
  • Job template names for generate:job --template
  • Job identifiers for job management commands
  • Credential keys for credentials commands
  • Database names and AWS profiles
  • File and directory paths
Back to top