HAX The CLI

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

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

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)
• hax site mysite --skeleton-machine-name clean-one --y - create a new HAXsite from an installed skeleton template
• hax audit - Audits web components for compliance with DDD (HAX design system)
• hax update - HAX CLI self update
• 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

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.

--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
  --import-site <char>                URL of site to import
  --import-structure <char>           import method to use:
                                      pressbooksToSite
                                      elmslnToSite
                                      haxcmsToSite
                                      notionToSite
                                      gitbookToSite
                                      evolutionToSite
                                      ploneToSite
                                      wordpressPagesToSite
                                      drupalBookToSite
                                      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
  --recipe <char>                     path to recipe file
  --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]                     Audits web components for compliance with
                                      DDD (HAX design system)
  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.
• 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/EKYJAjqGhf
• 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