GitHub v1.3.1

Coralite CLI

Reference

Dive into comprehensive Coralite CLI documentation, covering command-line tools, parameters, and workflows. Designed for developers leveraging native web technologies in static site generation.

This technical documentation provides an in-depth overview of the Coralite CLI, its command-line options, and usage examples.

Command Structure

The Coralite CLI is subcommand-based. Directories, output, and modes are declared in coralite.config.js (see the Configuration reference); the CLI only accepts flags that adjust the operation:

bash
Code copied!
  coralite <command> [options]

Commands

Command Description
coralite dev Start the development server with live reload and hot CSS updates.
coralite test Start the testing server used by coralite.config.js with mode: 'testing'.
coralite build Build the site for production.
coralite check Run a unified validation pass across Components, Plugins, and Pages.
coralite fix Apply deterministic AST auto-fixes in place.
coralite init-agent Scaffold AGENTS.md guidelines for AI coding assistants.
coralite validate-components Validate component templates, refs, serialization boundaries, and unused symbols.
coralite validate-pages Validate page documents against known component schemas.
coralite validate-plugins Validate plugin contracts, hook signatures, and serializable client options.

Shared Options (dev / test / build)

  • -v, --verbose (optional)

    • Description: Enable verbose logging output.
    • Example: coralite dev -v
  • -c, --clean (optional)

    • Description: Clear the output directory before building.
    • Example: coralite build -c
  • -a, --assets <mapping...> (optional)

    • Description: Static assets to copy during build. Supports both NPM packages and local paths. Multiple mappings can be provided separated by spaces. CLI assets take full precedence over config assets that target the same destination.
    • Formats:
      • NPM Package (3 parts): pkg:path:dest
      • Local Path (2 parts): src:dest (source path must start with ., .., or /)
    • Examples:
      • Copy from package: --assets my-package:dist/style.css:assets/style.css
      • Copy local file: --assets ./src/logo.png:assets/logo.png
      • Copy local directory: --assets ./src/docs:docs
  • --no-incremental (optional)

    • Description: Disable change detection optimization and force rebuilding all pages and components.
    • Example: coralite build --no-incremental

Configuration File Support

coralite dev, coralite test, and coralite build require a coralite.config.js file in the current working directory. Paths such as pages, components, and output, plus mode and cleanUrls, are all declared there via defineConfig imported from coralite — the CLI itself no longer accepts directory or output flags.

Examples

1. Start the development server:

bash
Code copied!
  coralite dev

2. Build for production with CLI asset mappings:

bash
Code copied!
  coralite build -a ./src/logo.png:assets/logo.png -a my-package:dist/style.css:assets/style.css

3. Start the testing server:

bash
Code copied!
  coralite test

coralite check (Workspace Audit)

The coralite check command performs a multi-domain static audit across Components, Plugins, and Pages in your workspace.

bash
Code copied!
  coralite check [options]
  • -c, --components <path> (optional)

    • Description: Path to the components directory (defaults to candidate directory or .).
    • Example: coralite check -c src/components
  • -p, --plugins <path> (optional)

    • Description: Path to plugins directory or single plugin file.
    • Example: coralite check -p src/plugins
  • --pages <path> (optional)

    • Description: Path to pages directory to audit HTML pages against component schemas.
    • Example: coralite check --pages src/pages
  • --format <format> (optional)

    • Description: Output report format. Options are "console" or "json". Default is "console".
    • Example: coralite check --format json
  • --strict (optional)

    • Description: Exit with status code 1 if any validation error or unused symbol warning is detected.
    • Example: coralite check --strict
  • --coverage (optional)

    • Description: Include component test and getter evaluation coverage metrics.
    • Example: coralite check --coverage

coralite fix (Unified AST Auto-Fixer)

The coralite fix command executes deterministic AST auto-fixers across Components, Pages, and Plugins. It modifies source files in-place and re-audits the codebase to confirm issues are resolved.

bash
Code copied!
  coralite fix [options]
  • -c, --components <path> (optional)

    • Description: Path to component files or directory to fix.
    • Example: coralite fix -c src/components
  • -p, --plugins <path> (optional)

    • Description: Path to a plugin file or plugins directory to fix.
    • Example: coralite fix -p src/plugins
  • --pages <path> (optional)

    • Description: Path to the pages directory to fix.
    • Example: coralite fix --pages src/pages
  • --migrate-pages (optional)

    • Description: Migrates page export default definePage({ ... }) configuration to flat named exports (export function server, export const meta, export const getters, …), and normalizes legacy export const server/export const paths handlers. Implies the pages domain when no page path is supplied; works with --dry-run. Files with unsupported constructs are left unchanged and reported.
    • Example: coralite fix --migrate-pages --dry-run
  • --dry-run (optional)

    • Description: Preview proposed AST fixes in colorized unified diff format without modifying files on disk.
    • Example: coralite fix --dry-run

coralite init-agent (AI Coding Rules Scaffolder)

The coralite init-agent command scaffolds zero-token AGENTS.md guidelines in the repository root for AI coding assistants such as Claude Code, Cursor, and GitHub Copilot.

bash
Code copied!
  coralite init-agent [options]
  • --cursor (optional)

    • Description: Also generate .cursor/rules/coralite.mdc for Cursor IDE context.
    • Example: coralite init-agent --cursor
  • --claude (optional)

    • Description: Also generate .claude/AGENTS.md for Claude Code CLI context.
    • Example: coralite init-agent --claude

coralite validate-pages (Page Document Validator)

The coralite validate-pages command audits static HTML pages for unknown custom element tags, missing required component attributes, and inline script encapsulation leaks.

bash
Code copied!
  coralite validate-pages [options]
  • --pages <path> (optional)

    • Description: Directory path containing page HTML files to validate.
    • Example: coralite validate-pages --pages src/pages
  • -c, --components <path> (optional)

    • Description: Component directory used to load known component schemas for attribute validation.
    • Example: coralite validate-pages --pages src/pages -c src/components

coralite validate-components (Component Validator)

The coralite validate-components command (alias: coralite validate:components) performs static AST and template validation across components to identify template syntax errors, missing refs, CSP violations, serialization leaks, and unused symbols.

bash
Code copied!
  coralite validate-components [options]
  • -c, --components <path> (optional)

    • Description: The path to the components directory to validate (defaults to src/components or project config).
    • Example: coralite validate-components -c src/components
  • --fix (optional)

    • Description: Apply 1-shot AST auto-fixes directly to component files (template expression lifting, ref injection, dynamic client imports).
    • Example: coralite validate-components --fix
  • --dry-run (optional)

    • Description: Preview proposed component fixes in unified diff format without writing to disk.
    • Example: coralite validate-components --fix --dry-run
  • --coverage (optional)

    • Description: Include component getter evaluation and client controller test execution coverage metrics.
    • Example: coralite validate-components --coverage
  • --format <format> (optional)

    • Description: Output report format. Options are "console" (colorised terminal output) or "json". Default is "console".
    • Example: coralite validate-components --format json
  • --strict (optional)

    • Description: Exit with a non-zero status code if any unused code or unreferenced symbols are found (ideal for CI pipelines).
    • Example: coralite validate-components --coverage --strict

coralite validate-plugins (Plugin Validator)

The coralite validate-plugins command (alias: coralite validate:plugins) validates plugin contracts, lifecycle hook signatures, serializable client options, and isomorphic boundaries.

bash
Code copied!
  coralite validate-plugins [options]
  • -p, --plugins <path> (optional)

    • Description: The path to a plugin file or plugins directory to validate (defaults to src/plugins).
    • Example: coralite validate-plugins -p src/plugins
  • --fix (optional)

    • Description: Apply AST auto-fixes for plugins (auto-currying context functions to Two-Phase pattern, injecting definePlugin wrapper).
    • Example: coralite validate-plugins --fix
  • --dry-run (optional)

    • Description: Preview plugin AST fixes in unified diff format without modifying disk.
    • Example: coralite validate-plugins --fix --dry-run
  • --format <format> (optional)

    • Description: Output report format. Options are "console" or "json". Default is "console".
    • Example: coralite validate-plugins --format json
  • --strict (optional)

    • Description: Exit with a non-zero status code if any plugin validation errors are detected.
    • Example: coralite validate-plugins --strict