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 templatehax wc --search "tooltip" - Search existing HAX elements (tag, title, description, tags) before building a new one; --format json for scriptshax 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 schemashax 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 translatedhax audit all - Runs all threehax 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 (, which Lit SSR does not write; use ). Options: , , , ,
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 managementhax-claudehax — ClaudeHAX plugin, /hax slash command, CLI operationhax-webcomponent-dev — hax webcomponent, HAXSchema, component scaffoldinghax-ecosystem-onboarding — environment setup, first scaffold, repo cloninghax-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:
# Warp / Oz / any agent — 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 presenthax-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.
- 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
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
--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
--org <char> organization for package.json
--author <char> author for site / package.json
--writeHaxProperties Write haxProperties for the element
--no-docs in a monorepo, leave out the docs data step
--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
--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
--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,
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
--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
-V, --version output the version number
--title <char> Title
--content <char> Page content
--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!
help [command] display help for command
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
Watch and Learn more about HAX here:
Related links and tech
