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):

hypermodern.yaml in current directory

.hypermodern/config.yaml in current directory

~/.hypermodern/config.yaml in home directory

/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