HQL CLI

The hql command has three workflows. Start with a file; create an app only when a web/mobile toolchain is needed; use package commands only to publish a library.

1. Run Or Compile A File

No project or manifest is required.

Command	Purpose
`hql <file.hql\|file.ts\|file.js>`	Run an HQL, TypeScript, or JavaScript entry
`hql <expression>`	Evaluate and print one expression
`hql run <entry>`	Explicit spelling of the same run command
`hql watch <file.hql>`	Re-run an HQL file when its graph changes
`hql compile <entry> -o <output.js>`	Bundle a mixed graph as ordinary JavaScript
`hql macroexpand <file.hql\|expression>`	Inspect macro expansion
`hql lsp`	Run the language server on standard I/O
`hql explain <CODE>`	Explain an HQL diagnostic

The entry may mix .hql, .ts, .tsx, .js, .jsx, .mjs, .cjs, and .json modules. For example, main.ts may import ./math.hql, and HQL may import local JavaScript or TypeScript modules.

hql hello.hql
hql '(+ 1 2)'
hql main.ts
hql hello.hql --typecheck=warn
hql hello.hql --typecheck=off
hql hello.hql -- alice --verbose

hql run defaults to strict type-checking. Use warn to continue after diagnostics or off to bypass the TypeScript checking pipeline. Arguments after -- belong to the user program.

Compilation accepts the same mixed entry graph:

hql compile hello.hql -o hello.js
hql compile main.ts -o app.js
hql compile app.hql -o app.js --pure
hql compile app.hql -o app.js --react-dom

--pure enables pure-mode import trust checks. --react-dom and --react-native select HQL element lowering when compiling React source outside a managed app project.

hql watch keeps a warm process and re-runs an HQL entry when .hql, .js, .ts, or .json files in its directory change. It is the editing loop for a normal script; hql dev means an application project.

2. Create A Project

Choose an application target explicitly:

Command	Purpose
`hql new <path> --kind web`	Create a minimal web app
`hql new <path> --kind mobile`	Create a minimal mobile app
`hql new <path> --kind cli`	Create a command-line app
`hql new <path> --kind library`	Create a reusable library
`hql new <path> --kind web --example todo`	Create the larger React example
`hql dev [path]`	Compile, watch, and run an app
`hql build [path]`	Build the current project kind
`hql run ios\|android\|web [path]`	Run a mobile target
`hql build ios\|android\|web [path]`	Build a mobile target

Web:

hql new app --kind web

Mobile:

hql new app --kind mobile
hql dev app
hql run ios app

Every project has one source manifest, hql.json. Generated package metadata, bridges, caches, and host configuration are ignored implementation state. hql dev compiles HQL, installs missing dependencies, starts the target, and watches for changes. In an interactive terminal, hql new ... --kind web starts the new web app immediately; hql dev is the resume command.

For a CLI project or one HQL file, hql build creates a single native executable containing the application and its runtime:

hql build tool -o dist/tool
hql build script.hql -o script

Use --dry-run on dev, run, or build to compile and print the delegated work without starting a server, Expo, or EAS.

3. Publish A Package

The simple case needs only mod.hql:

hql publish --dry-run
hql publish

HQL infers name, version, entry, and npm plus JSR targets. Use --target npm, --target jsr, or --target all to override the registry selection.

Command	Purpose
`hql init [path]`	Initialize package metadata
`hql add [path] <specifier>`	Add an npm, JSR, or URL import
`hql remove [path] <name>`	Remove a dependency
`hql install [path] [--reload]`	Install package dependencies
`hql update [path] [name]`	Update package dependencies
`hql info <specifier>`	Inspect a dependency specifier
`hql check [path] [--json]`	Validate package configuration
`hql build [path] --target jsr\|npm\|all [--out <dir>]`	Build distributable artifacts
`hql pack [path] [--target jsr\|npm\|all]`	Prepare publishable artifacts
`hql publish [path] [--dry-run] [--target ...]`	Verify and publish ESM
`hql config [write] [path]`	Read or normalize package config

hql new my-lib --kind library
hql add my-lib npm:lodash-es@^4.17.21
hql publish my-lib --dry-run

See Packages for dependency ownership and distribution boundaries.

Command Help

hql --help
hql help run
hql help publish

The source of truth for dispatch and accepted flags is src/hql/cli.ts; documentation checks keep public examples aligned with it.