HAX The CLI

Rapidly build web components for the Web that work with HAX. HAX The Web's CLI tools empower you to rapidly..

Onboarding

New to the HAX ecosystem? Start here — the single onboarding guide covers prerequisites, cloning the core repos, installing, and running each project locally.

# this allows you to then use hax command
npm install @haxtheweb/create --global
# then run this for interactive prompt
hax start

Who the hax CLI is for

• Web component developers — scaffold HAX-capable, i18n-wired, DDD-driven components in one command.
• Site builders and course designers — create, serve, and publish HAXsites from the terminal, or hand the same work to an AI agent via the bundled skills.
• AI coding agents and their users — bundled interface skills and the PRAW plugin marketplace teach any agent the full CLI surface.
• Campus IT and instructional designers — import existing content (Pressbooks, Notion, GitBook, Word, HTML, and more) into portable HAX sites.

Commands

Default / global / new context

• hax start - fun ascii art and interactive CLI (via clack )
• hax webcomponent my-element --y - Make a new HAX capable, i18n wired, Design system (DDD) driven web component
  • if in a monorepo root, will place in correct location / inherit settings
• hax site mysite --y - create a new HAXsite (HAXcms, single site)
  • in scripts and agents use hax site mysite --y --no-i so nothing prompts or launches a dev server (implied automatically when there is no TTY or CI is set)
• hax site mysite --skeleton-machine-name clean-one --y - create a new HAXsite from an installed skeleton template
• hax wc --search "tooltip" - Search existing HAX elements (tag, title, description, tags) before building a new one; --format json for scripts
• hax audit - Audits web components for compliance with DDD (HAX design system)
• hax audit schema - Validates site.json, skeletons, haxProperties (and their demoSchema / locales), appstore.json and Merlin commands against the HAX schemas
• hax audit i18n - Finds English hardcoded in Lit templates (text and attributes like aria-label, title, placeholder) that should come from this.t so it can be translated
• hax audit all - Runs all three
• hax audit theme - Checks HAXcms theme source (a site's custom/src/, or theme files under the current directory) against the theme contract: extends HAXCMSLitElementTheme, static get tag() + customElements.define, #contentcontainer > #slot > <slot> for the HAX editor, a skip-link rendered first, super.styles, dark mode (light-dark() needs color-scheme), a responsive @media fallback, site-region names the Appearance dialog can assign, globalThis and no optional chaining. Each finding's rule id matches a @hax-theme-contract marker in the starter template. Errors fail; warnings fail with --strict. --format json gives rule, severity, file, line, message and fix for agents. Not part of all
• hax audit ssr - Report-only: server-renders every element in wc-registry.json with @lit-labs/ssr and buckets the result (rendered / shell / empty / no shadow root / threw) with output and style sizes. Never fails on render problems and is not part of all. Runs with a small inert DOM environment (window, event target, observers, element query/child/class/style APIs as no-ops) so elements fail only for their own reasons; --no-shim turns that off to show what elements manage unaided. Also reports elements that supply their own progressiveEnhancement fallback markup and the size of a primitive-tag stylesheet that covers it, and flags HTML boolean attributes written as ="false" (a .checked=${value} property binding on a native input renders as checked="false", which browsers read as on until hydration; use ?checked=${value}) or a native element's address bound as a property in the element's own source (<iframe .src=${url}>, which Lit SSR does not write; use src=${url}). Options: --only <tags>, --timeout <ms>, --save-html <dir>, --no-shim, --format json
• hax update - HAX CLI self update
• hax platform status - Installed vs latest HAXcms release, published security advisories that affect it, and the command that updates this kind of install (--path <install>, --format json). Outside an install it reports on the haxcms-nodejs that hax serve uses. hax start mentions a newer release (checked at most weekly) and flags a missing security fix on every run
• hax platform upgrade - Upgrade a haxcms-php install by running its own scripts/platform-upgrade.php: checks the release against SHA256SUMS and platform-manifest.json, backs up the code files it changes, never touches site data (--to <x.y.z>, --dry-run, --overwrite-modified, --allow-downgrade, --y). hax platform verify compares code files with the release manifest; hax platform rollback undoes the last upgrade. npm, Docker and git installs are pointed at the tool they came from. Not available on HAXiam (haxiam-managed) deployments, where the host manages HAXcms
• hax party - Display options to join the HAX community and get involved!
• hax skills list - List bundled agent skills shipped with the CLI
• hax skills install --all - Install all bundled skills into ~/.agents/skills/ for any agent to use
• hax skills install <name> - Install a specific bundled skill

Bundled Agent Skills

This CLI ships interface skills in src/skills/ (compiled to dist/skills/) that teach agents how to use the hax CLI. These are version-locked to the CLI — when a command or flag ships, the matching skill updates in the same release.

Bundled skills:

• hax-site-building — HAXcms site creation, JOS, site.json, page management
• hax-claudehax — ClaudeHAX plugin, /hax slash command, CLI operation
• hax-webcomponent-dev — hax webcomponent, HAXSchema, component scaffolding
• hax-ecosystem-onboarding — environment setup, first scaffold, repo cloning
• hax-rpg-character — extending the rpg-character avatar with new pixel-art pieces

Install them for your agents:

hax skills install --all          # all interface skills → ~/.agents/skills/
hax skills install hax-site-building  # specific skill
hax skills install --all --path ./test-site/.agents/skills  # custom target

Workflow and knowledge skills (media ingestion, OpenStax conversion, DDD design system, issue analysis, rule management, Bloom's taxonomy) live in the PRAW repository and are not bundled with the CLI.

AI integration

HAX works with any AI coding agent. There are two install paths depending on your tool:

# Any agent (Codex, Copilot, Warp and others) — install the bundled interface skills
hax skills install --all

# Claude Code — add the PRAW marketplace and install the onboarding plugin
/plugin marketplace add haxtheweb/praw
/plugin install hax-onboarding@haxtheweb

The PRAW marketplace ships three Claude Code plugins:

• hax-onboarding — golden-path slash commands plus an auto-install hook that ensures the hax CLI is present
• hax-site-ops — the site-operations skill and reference docs (the renamed ClaudeHAX plugin, which resolves the old name collision)
• openstax2hax — OpenStax-to-HAX conversion, folded in unchanged

Golden path from zero to a running site:

hax site my-hax-site --y --no-i
cd my-hax-site && hax serve
# open the local URL printed by hax serve (http://localhost)

For AI agents

• Always pass --y --no-i in scripts. With no TTY (agent sandboxes, CI, piped shells) the CLI implies --no-i on its own.
• Use the global hax command, not npx hax (that resolves to a different npm package).
• Inside a site, run hax site (or hax site --format json) first. It reports the site, its key files, which files are managed, and the scriptable commands.
• With --format json or --format yaml, stdout carries only the data, so it can be piped straight into jq or a parser. Progress messages go to stderr.
• A mistyped action (for example hax site node:ad) exits with status 1 and suggests the closest action.
• hax list --format json describes every command, action and option, so you can discover the CLI without parsing --help.
• hax @name site:stats runs against a site named in ~/.haxtheweb/aliases.yml or a project hax.aliases.yml, from any folder. Create them with hax alias add <name> (inside the site, or --root <folder>), list them with hax alias, remove with hax alias remove <name>.
• hax site site:validate exits 1 when a site has structural errors; run it before and after bulk changes.
• Every site ships AGENTS.md, llms.txt and .well-known/agent-skills/index.json. Read those before changing anything.

See the AI integration page on the HAX documentation site for the full guide.

--help

Run hax help or hax webcomponent --help or hax site --help for up-to-date listing. hax list --format json gives the same information as JSON.

Usage: hax [options] [command]

Options:
  --v                                 Verbose output
  --debug                             Output for developers
  --format <char>                     Output format; json (default), yaml
  --path <char>                       where to perform operation
  --name <char>                       name of the project/web component
  --npm-client <char>                 npm client to use (must be installed) npm,
                                      yarn, pnpm (default: "npm")
  --y                                 yes to all questions
  --skip                              skip frills like animations
  --quiet                             remove console logging
  --auto                              yes to all questions, alias of y
  --no-i                              prevent interactions / sub-process, good
                                      for scripting
  --agent                             mark changes as made by an AI agent in the
                                      site's history (same as HAX_ACTOR=agent)
  --to-file <char>                    redirect command output to a file
  --no-extras                         skip all extra / automatic command
                                      processing
  --root <char>                       root location to execute the command from
  --lang <char>                       Language for prompts and messages, e.g.
                                      es, fr, ja (defaults to your system
                                      language)
  --site-lang <char>                  Language of a new site, e.g. en, es,
                                      zh-CN, pt-BR (defaults to English)
  --org <char>                        organization for package.json
  --author <char>                     author for site / package.json
  --template <char>                   template type to use (compliant, minimal,
                                      training, monorepo)
  --writeHaxProperties                Write haxProperties for the element
  --no-docs                           in a monorepo, leave out the step that
                                      writes the element's docs data
                                      (lib/<tag>.docs.json) when it builds
  --force                             force creation even if name exists in
                                      registry
  --import-site <char>                URL of site to import
  --import-structure <char>           import method to use:

pressbooksToSite

elmslnToSite

haxcmsToSite

notionToSite

gitbookToSite

evolutionToSite

ploneToSite

wordpressPagesToSite

drupalToSite

openstaxToSite

vitepressToSite

quartoToSite

htmlToSite

docxToSite

xlsxToSite
  --node-op <char>                    node operation to perform
  --item-id <char>                    node ID to operate on
  --domain <char>                     published domain name
  --title-scrape <char>               CSS Selector for `title` in resource
  --content-scrape <char>             CSS Selector for `body` in resource
  --content-format <char>             format of --content for node:add /
                                      node:edit: html (default), md, json, yaml
  --description <char>                description of the page (node:add /
                                      node:edit) or of the new site
  --items-import <char>               import items from a file / site
  --custom-theme-name <char>          custom theme name
  --custom-theme-template <char>      custom theme template; (options: base,
                                      starter, polaris-flex, polaris-sidebar)
  --skeleton-file <char>              path to skeleton JSON file
  --skeleton-machine-name <char>      skeleton machine name (installed template)
                                      to create a site from
  --search <char>                     search query text or simple selector (for
                                      site:search)
  --search-field <char>               comma-separated fields for text search
                                      (title,slug,description,tags,content,all)
  --search-case-sensitive             case-sensitive text search
  --search-limit <char>               max number of site search matches to
                                      return
  --search-selector                   treat --search as a selector query (tag,
                                      tag[attr], tag[attr="value"], [attr])
  --search-mode <char>                search mode override (text or selector)
  --source <char>                     rsync source directory or remote path
  --destination <char>                rsync destination directory or remote path
  --exclude <char>                    comma-separated patterns to exclude from
                                      rsync
  --dry-run                           perform rsync dry run
  --delete                            delete extraneous files from destination
  --repos <char...>                   repositories to clone
  --export-format <char>              export format for site:export (pdf, docx,
                                      epub, html, zip, markdown, skeleton)
  --revision-id <char>                revision ID for site:revisions
  --restore                           restore a revision (used with
                                      site:revisions)
  --target-path <char>                target subdirectory for files-upload
  --file-uuid <char>                  file UUID for files-delete
  --file-path <char>                  file path (alternative to UUID) for
                                      files-delete
  --replace <char>                    replacement text for search-replace
  --confirm                           confirm destructive search-replace
                                      operation
  --destroy-confirm                   confirm removing matched text in
                                      search-replace
  --only <char>                       site:rebuild targets to rebuild, comma
                                      separated (rss, sitemap, search, llms,
                                      managed, skills)
  --count <char>                      number of pages for node:generate (default
                                      10, max 200)
  --rsync <char>                      rsync target to store with `hax alias add`
                                      (user@host:/path)
  --project                           with `hax alias add|remove`, use
                                      hax.aliases.yml in this folder instead of
                                      ~/.haxtheweb/aliases.yml
  -V, --version                       output the version number
  --title <char>                      Title
  --content <char>                    page content for node:add / node:edit: a
                                      URL (http:// or https://) is fetched, an
                                      existing file path is read, anything else
                                      is inline HTML
  --slug <char>                       Path (slug)
  --published <char>                  Publishing status
  --tags <char>                       Tags
  --parent <char>                     Parent
  --order <char>                      Order
  --theme <char>                      Theme
  --hide-in-menu <char>               Hide in menu
  -h, --help                          display help for command

Commands:
  start                               Select which hax sub-program to run
  update [options]                    hax cli self update
  serve                               Launch HAXsite in development mode
                                      (http://localhost)
  site [options] [action]             create or administer a HAXsite
  wc|webcomponent [options] [action]  Create Lit based web components, with HAX
                                      recommendations
  audit [options] [type]              Audits for HAX compliance: DDD design
                                      system (default), HAX schemas,
                                      translatable text, or all of them
  party [options] [action]            Party time! Join the HAX community and get
                                      involved!
  skills [options] [action] [name]    List and install bundled agent skills for
                                      HAX ecosystem agents
  list [options]                      List every command, action and option
                                      (--format json for tools and agents)
  alias [options] [action] [name]     List, add and remove named sites (aliases)
                                      for `hax @name ...`
  completion [shell]                  Print a shell completion script
  help [command]                      display help for command

hax site --help lists the site actions:

Usage: hax site [options] [action]

Arguments:
  action                          Actions to perform on site include:

start - Launch site in browser
                                  (http://localhost)

serve - Launch site in development mode

node:stats - Node Stats / data

node:add - Add a new page

node:edit - Edit a page

node:delete - Delete a page

node:generate - Generate placeholder pages

site:stats - Site Status / stats

site:items - Site items

site:items-import - Import items (JOS /
                                  site.json)

site:list-files - List site files

site:search - Search site content

site:tags - List site tags

site:blocks - List site block usage

site:analytics - Site analytics metadata

site:revisions - List or restore item
                                  revisions

site:validate - Validate site structure and
                                  content

site:rebuild - Rebuild generated files
                                  (feeds, sitemap, search, llms.txt)

site:archive - Archive the whole site to a
                                  .tar.gz

site:restore - Restore the site from an
                                  archive

site:logs - Show recent CLI log entries

site:list - List sites in this folder

site:export - Export site in a format

site:theme - Change theme

site:element - Add new Lit component to
                                  custom/src

site:html - Full site as HTML

site:md - Full site as Markdown

site:schema - Full site as HAXElementSchema

site:skeleton-export - Export site as
                                  skeleton template

site:skeleton-install - Install skeleton
                                  template

site:sync - Sync git repo

site:rsync - Rsync site to remote/local
                                  directory

site:surge - Publish site to Surge.sh

site:netlify - Publish site to Netlify

site:vercel - Publish site to Vercel

setup:github-actions - Setup GitHub Actions
                                  deployment

setup:gitlab-ci - Setup GitLab CI deployment

setup:replit - Setup Replit configuration

issue:general - Issue: Submit an issue or
                                  suggestion

issue:theme - Issue: Suggest custom theme

Pass values that start with - as --flag=value (for example --description="-1 is the answer"), so they are not read as another flag.

Examples

For a detailed list of example commands that you can perform with hax see examples.

Manual

Linux / macOS

Run man hax to get detailed manual.

Alternative Usage

# also this will invoke 1x
npx @haxtheweb/create
# this is same as above, better windows CLI support
npm init @haxtheweb

# script creating a new element called my-element w/ all defaults
npm run hax -- --name my-element --y

Windows problems?

Try setting a different cache path to load from npm config set cache C:\tmp\nodejs\npm-cache --global

If you wish to use PowerShell over Command Prompt, you may need to change your execution policy to allow scripts using the Set-ExecutionPolicy command with the -ExecutionPolicy and -Scope parameters. You should not need to do this if you are using Command Prompt.

# To see your current execution policy
Get-ExecutionPolicy

Set-ExecutionPolicy command documentation: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.4

Follow the prompts and let's HAX the Web together!

Web component

Step through answering basic install questions to build a HAX capable web component that works anywhere! Features:

• LitElement based
• DDDSuper class which adds our design system in
• Common conventions used to demonstrate and work with property binding
• Minor CSS variable inclusion for initial learning

HAX Site

Build a HAX site that can be published and transported anywhere. Your users might love it on the front end, now you get the simplicity of building on the CLI.

• Same HAX sites you can create via front end
• Templated files that work just like any HAX site
• End points baked in to do CLI commands for common endpoint operations like adding pages, deleting and editing.
• Ability to import via URL just like the front-end
• Ability to export a site as a skeleton JSON template and install skeletons for reuse
• Ability to create a new site from a local skeleton file or installed skeleton machine name
• Theme development starting point to be able to build themes locally
• Primed to publish to gh-pages, vercel and more

HAX Audit

Audits your HAX based web components to suggest improvements to better align with DDD, the design system built into HAX components.

• Use .dddignore file to instruct audit program what files should be ignored. Each component generated comes with a .dddignore file in its root directory.
• hax audit i18n skips test, demo, locales and build folders. Mark intentional English (brand names, code samples) with an i18n-ignore comment on that line or the line above, i18n-ignore-file anywhere in a file, or list paths in a .i18nignore file (same format as .dddignore).
• Run command from root of the component project.
• Provides suggested changes for component CSS to align with DDD design standards, if a change cannot be suggested, developer will be refered to look at the manual for a change that works for them!

.dddignore Template

# Directories
# (Must start with with / or \, as seen below)
/.github # Inline comments are supported
/.vscode
/.idea
/locales
\test
/dist
/build
/public # ignored by program regardless of presence in .dddignore
/node_modules # ignored by program regardless of presence in .dddignore

# Files
# (Must include filename and extension, as seen below)
LICENSE
.dddignore
.editorconfig
.gitignore
.nojekyll
.npmignore
.surgeignore
rollup.config.js

# File extension
# (Must start with *, as seen below)
*.md
*.yml
*.json
*.toml
*.mjs
*.cjs
*.png
*.ico
*.svg
*.jpg
*.jpeg

Get Help / Issues / Support

• Discord Channel - https://discord.gg/aCGxmRHEJP
• Unified issue queue - https://github.com/haxtheweb/issues/issues
• DDD Documentation - https://haxtheweb.org/documentation/ddd
• Using Merlin directly in any HAX spaces and type "Issue" to jump start a report!

Watch and Learn more about HAX here:

• Try Hax: https://hax.cloud
• HAXCellence https://haxtheweb.org/what-is-hax
• Youtube channel - https://www.youtube.com/@haxtheweb

Related links and tech

• NPM Package list
• HAXcms (NodeJS)
• HAXcms (PHP)
• Storybook docs
• HAX [dot] PSU
• HAX doc site
• HAX + 11ty