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

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

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

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"

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:

# Bash
hypermodern completion bash >> ~/.bashrc

# Zsh
hypermodern completion zsh >> ~/.zshrc

# Fish
hypermodern completion fish >> ~/.config/fish/completions/hypermodern.fish
Back to top