CLI Commands

Hexa CLI command groups:

• hexa new
• hexa build
• hexa add
• hexa generate

hexa new

Scaffold a new extension project.

hexa new [name] [--platform chrome,firefox,...]

Argument / Option	Values	Notes
[name]	string	Prompted if omitted
--platform	chrome, firefox, safari, opera, edge, brave	Comma-separated list

hexa build

Compile and generate extension artifacts.

hexa build [--platform chrome] [--mode production] [--target all] [--watch]

Option	Values	Default
--platform	chrome, firefox, safari, opera, edge, brave	chrome
--mode	development, production	config or production
--target	all, ui, content, background	all
--verbose	flag	false
--watch	flag	false
--no-auto-open-browser	flag	auto-launch enabled

Notes:

• Watch mode is driven by hexa build --watch.
• There is no separate hexa dev command.
• In Chrome watch mode, Hexa launches a Chromium-compatible browser automatically with the unpacked extension from dist/chrome/development.
• Hexa prefers Chromium or Chrome for Testing when available because current branded Google Chrome builds block --load-extension for unpacked extensions.
• Auto-launch opens chrome://extensions in the dedicated Hexa dev profile.
• Hexa pre-seeds the extension action as pinned in that dev profile.
• If the extension is not visible, enable Developer mode there and refresh once.
• Use --no-auto-open-browser to disable automatic Chrome launch.

Compiler options (hexa-cli.config.json)

compilerOptions supports Vite-style build flags with Hexa camelCase keys:

Key	Type	Notes
minify	boolean | "esbuild" | "terser"	true maps to "esbuild"
cssMinify	boolean | "esbuild" | "lightningcss"	CSS minifier strategy
sourceMap	boolean | "inline" | "hidden"	Mapped to Vite build.sourcemap
terserOptions	object	Used only when minify: "terser"

Example profiles:

{
  "compilerOptions": {
    "minify": false,
    "cssMinify": false,
    "sourceMap": true,
    "terserOptions": {}
  },
  "environments": {
    "production": {
      "compilerOptions": {
        "minify": "terser",
        "cssMinify": "lightningcss",
        "sourceMap": false,
        "terserOptions": {
          "compress": {
            "drop_console": true
          }
        }
      }
    }
  }
}

UI options (hexa-cli.config.json)

Key	Type	Default	Notes
ui.parallelBuild	boolean	true	Runs managed popup + managed devtools builds in parallel during standard build mode. Set to false to force sequential managed UI builds.

hexa add

Add feature blocks to an existing project.

add content

hexa add content <name> <urlList> [--run-at document-idle]

add background

hexa add background <name> [--allow-multiple]

add ui

hexa add ui popup [--framework react|vue|svelte|solid]
hexa add ui devtools [--framework react|vue|svelte|solid]
hexa add ui newtab [--framework react|vue|svelte|solid]
hexa add ui sidepane [--framework react|vue|svelte|solid]

--framework overrides the surface's scaffolded framework for this command only. When omitted, it falls back to the project's ui.framework (persisted to hexa-cli.config.json on first managed surface), defaulting to react.

popup ↔ sidepane toolbar-action conflict

Popup and side panel share the same toolbar action button. Both can be configured at the same time — nothing is deleted — but only one of them opens from a plain toolbar click:

• Adding popup while sidepane is configured: the toolbar click will open the popup, so the side panel can no longer be opened by that click (it stays reachable via context menu, a keyboard command, or a button inside the popup). Hexa CLI prints this explanation and asks for confirmation before scaffolding the popup.
• Adding sidepane while popup is configured: the toolbar click keeps opening the popup, so the new side panel won't open from that click either. Hexa CLI prints an informational note and proceeds — no confirmation required.

The confirmation prompt is interactive (TTY) by default. Pass --yes (or -y) to confirm automatically — required in CI or any non-interactive shell, where the command otherwise throws an error explaining how to proceed.

hexa add ui popup --yes   # skip the interactive confirmation

add worker

Scaffold a @Worker class for CPU-bound or DOM-dependent background work.

hexa add worker <name> [--environment compute|dom]

Option	Values	Default	Notes
--environment	compute, dom	compute	dom workers run inside an offscreen document (Chromium) when the build needs DOM APIs (e.g. canvas, WASM helpers requiring a document).

Output: src/background/workers/<name>.worker.ts. The worker's @Worker({ name }) value is automatically suffixed with -worker if not already present, so hexa add worker ocr scaffolds @Worker({ name: 'ocr-worker', ... }).

add view

Scaffold a content @View shadow-DOM component (an overlay, toast, or floating widget injected into the page).

hexa add view <name>

Output under src/content/ui/<name>/:

• <name>.view.ts — the @View-decorated HexaView subclass
• <name>.component.(tsx|vue|svelte) — the framework component
• <name>.css — shadow DOM styles (imported with ?inline)

The component is scaffolded using the project's ui.framework setting (defaults to react when not configured). The framework choice is project-wide — mixed frameworks within a single extension are not supported.

add handler

hexa add handler <name> <contentClass>

Shared options for add subcommands:

• --cwd <path>
• --dry-run
• --force
• --verbose
• --yes / -y — confirm interactive prompts automatically (required in non-interactive/CI shells when a prompt would otherwise appear, e.g. the popup/sidepane conflict)

hexa generate

Generate classes and store scaffolds.

generate controller

hexa generate controller <name> [--namespace value]

generate handler

hexa generate handler <name> [--namespace value]

generate service

hexa generate service <name> <context>

Contexts: background, content, general, ui.

generate reducer

hexa generate reducer <name> <context>

Contexts: background, content.

generate state

hexa generate state <name> <context>

Requires an existing matching reducer file.

Shared options for generate subcommands:

• --cwd <path>
• --dry-run
• --force
• --verbose

generate output directories

CLI schematics commands (hexa generate ... and hexa add handler ...) use fixed source-root directories:

• controllers: src/background
• handlers: src/content
• services: src/services
• workers (hexa add worker): src/background/workers
• content views (hexa add view): src/content/ui/<name>

For reducers and state generation, directories are context-based under src/background/store and src/content/store.

Where to go next

• Build internals and AOT behavior: Build Pipeline
• Output merge semantics: Manifest Patching
• Live reload behavior by platform: HMR