Coralite CLI

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

The basic command structure for the Coralite CLI is as follows:

coralite [options]

The Coralite CLI accepts several options to configure its behavior. Here's a detailed list of available options:

• -c, --components <path> (required)

  • Description: The file system path to the directory containing Coralite component files.
  • Example: --components path/to/components

• -p, --pages <path> (required)

  • Description: The file system path to the directory containing page files that will be rendered.
  • Example: --pages path/to/pages

• -o, --output <path> (required)

  • Description: The output directory for the generated site. If the specified directory does not exist, it will be created.
  • Example: --output path/to/dist

• -m, --mode <mode> (optional)

  • Description: The build mode. Can be "production" or "development". Default is "production".
  • Example: --mode development

• -i, --ignore-attribute <key=value...> (optional)

  • Description: Ignore elements by attribute name-value pair during parsing. Multiple pairs can be provided separated by spaces.
  • Examples:
    • Ignore <div data-ignore> elements: --ignore-attribute data-ignore=true
    • Ignore multiple elements: --ignore-attribute data-ignore=true class=test-only

• -s, --skip-render-attribute <key...> (optional)

  • Description: Parse elements but exclude them from final render output based on attribute presence.
  • Example: --skip-render-attribute data-client-only

• -d, --dry-run (optional)

  • Description: Run the CLI in dry-run mode. This displays information about generated documents and their content without actually writing files to the output directory.
  • Example: coralite -c src/components -p src/pages -o dist --dry-run

• -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 override config assets if they 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

The Coralite CLI automatically looks for a coralite.config.js file in the current working directory. If found, it will merge its configuration with the CLI options.

1. Generate a site with default options:

coralite -c src/components -p src/pages -o dist

2. Ignore specific elements during parsing and run in dry-run mode:

coralite -c src/components -p src/pages -o dist --ignore-attribute data-ignore=true class=test-only --dry-run

3. Using with a configuration file:

When a coralite.config.js file exists in your project the CLI will automatically load it:

coralite -c src/components -p src/pages -o dist

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 and Plugins. It modifies source files in-place and re-audits the codebase to confirm issues are resolved.

coralite fix [--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