Coralite CLI

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

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:

coralite <command> [options]

• -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

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.

1. Start the development server:

coralite dev

2. Build for production with CLI asset mappings:

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

3. Start the testing server:

coralite test

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

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

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.

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

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.

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

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

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

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.

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

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

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