HHY Reference
CLI Reference
Run, check, format, use the REPL, inspect dry-run plans, and profile performance.
HHY 1.7.1 implementation and compatibility
1.7.1 passes local tests, four-platform CI and release validation. Language specification 1.0 remains frozen. Official sample, HTML and macOS/Linux Database 1.0.0 extensions are verified compatible. VS Code 0.2.0 and Sublime 0.1.0 retain independent versions; syntax and editor contract checks pass.
HIR, six optimization passes, integer MIR, type-feedback guards/deopt and local List scalar replacement are implemented. Explicitly enable HHY_COMPILER=ir, HHY_FEEDBACK_SPECIALIZATION=1 and HHY_SCALAR_REPLACEMENT=1; direct Bytecode remains default. Real workloads have not met default-enablement benefit gates. Scalar replacement retains original GC/quota reservations.
Optimization switches, verification and supported scopev1.7.1 implementation1.7.1 release notesReleased capabilities and limitsVersion and release identity
Use --version to confirm the binary version, project author, open-source license, and official contact details. Source builds use ./build/hhy; release archives or PATH installations can invoke hhy directly.
hhy 1.7.1 © 2026 HHY Language contributors Author: houhuiyang License: Apache License 2.0 https://hhylang.dev/ huiyang.hou@qq.com
Actual HHY 1.7.1 command output. The CLI reports the version, author, license, website, and contact address directly.
Complete command set
hhy script.hhy [args...]
hhy run script.hhy [args...]
hhy run --engine ast|bytecode script.hhy [args...]
hhy repl
hhy check script.hhy...
hhy fmt script.hhy...
hhy fmt --check script.hhy...
hhy ast script.hhy
hhy bytecode script.hhy
hhy bytecode --metrics script.hhy
hhy tokens script.hhy
hhy run --dry-run script.hhy
hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy
hhy serve app.hhy [args...]
hhy serve --dev app.hhy [args...]
hhy serve --engine ast|bytecode --limit max_memory=256mib app.hhy -- [args...]
hhy profile script.hhy [args...]
hhy profile --engine ast|bytecode script.hhy [args...]
hhy profile --cpu script.hhy
hhy profile --heap --format json --output profile.json script.hhy
hhy check --format json script.hhy...
hhy contracts --format json
hhy install [--yes] [--dry-run] [--upgrade] [--locked] [--offline] [--lockfile FILE] [--cache DIR] [--registry DIR --trust-root FILE] <package-or-path>
hhy lock [--lockfile FILE] --registry DIR --trust-root FILE <package>
hhy fetch --locked [--lockfile FILE] [--cache DIR] --registry DIR --trust-root FILE
hhy rollback <package>
hhy doctor extensions [--lockfile FILE] [--cache DIR]
hhy list
hhy remove <package>
hhy --version
hhy -V
hhy --help
hhy -h| Command | Purpose |
|---|---|
| hhy contracts --format json | Export callable contracts |
| hhy install | Install or upgrade extensions |
| hhy lock | Resolve dependencies and write lockfile |
| hhy fetch --locked | Cache locked dependencies |
| hhy rollback | Restore the previous verified extension |
| hhy doctor extensions | Verify lockfile, cache and installed extensions |
| hhy list / hhy remove | List or remove extensions |
| hhy check --format json | Emit JSON diagnostics |
| hhy run | Run a script and pass args |
| hhy run --engine ast|bytecode | Select the AST fallback or Bytecode engine explicitly |
| hhy serve | Run a persistent Web application configured by web.listen |
| hhy serve --dev | Watch source files and reload the Web application |
| hhy serve --engine ast|bytecode | Select the execution engine used by Web handlers |
| hhy serve --limit NAME=VALUE | Apply repeatable Web Runtime resource limits |
| hhy profile | Analyze CPU hotspots, call counts, and managed-Heap allocations |
| hhy repl | Start the interactive environment |
| hhy check | Check syntax and core semantics |
| hhy fmt | Write canonical formatting |
| hhy fmt --check | Check formatting only |
| hhy ast | Print the AST |
| hhy bytecode | Compile, verify, and disassemble Bytecode |
| hhy bytecode --metrics | Emit cache-admission compile/verify/prepare metrics as JSON |
| hhy tokens | Print Lexer tokens |
| hhy run --dry-run | Preview a redacted execution plan |
hhy script.hhy is shorthand for hhy run script.hhy. Use -- after Runtime options when script arguments may begin with a dash.
serve · Persistent Web applications
serve loads and checks an HHY Web application, then keeps the process alive. --dev safely reloads after source changes; --engine selects AST or Bytecode; repeatable --limit options bound Runtime resources. HTTP settings such as host, port, max_body, and workers remain explicit in web.listen, while trailing positional values are exposed through read-only args.
hhy serve app.hhy
hhy serve --dev app.hhy -- 8080
hhy serve --engine bytecode \
--limit max_memory=256mib \
--limit max_runtime=30s \
app.hhy -- 8080 production| Option/argument | Behavior |
|---|---|
| --dev | Watch the entry file and imported modules, then reload after changes |
| --engine ast|bytecode | Select the handler engine explicitly; Bytecode is the default |
| --limit NAME=VALUE | Override memory, runtime, file, process, parallelism, HTTP-body, regex, or recursion limits; repeatable |
| --dry-run | Evaluate the plan while blocking external effects; mainly useful for startup validation |
| -- | End Runtime options and pass every remaining value through args |
Bytecode cache admission evidence
v1.7.1 adds read-only --metrics output for measuring real compile+verify and execution-plan verification cost. Across five fixed workloads and 21 paired fresh-process samples, compile+verify medians were 0.004–0.012 ms, only 0.0078%–0.1341% of cold-run wall time, below the joint 1 ms and 20% thresholds.
{"bytecode_format_version":1,"compile_verify_ns":9000,"constants":21,"instructions":40,"schema_version":1,"source_bytes":167,"stream_kernel_version":1,"stream_kernels":1,"tool":"hhy bytecode --metrics","verify_prepare_ns":4000}CPU and Heap profiling
profile executes the script and collects CPU and managed-Heap data in the same run by default. Reports go to stderr, leaving script stdout unchanged, and the command preserves the script's exit code.
hhy profile examples/09-profile-algorithms.hhy -- fibonacci 20
hhy profile --cpu examples/09-profile-algorithms.hhy fibonacci 20
hhy profile --heap --format json --output profile.json examples/09-profile-algorithms.hhy fibonacci 20| Option | Behavior |
|---|---|
| --cpu | Collect only 1ms process-CPU samples and call counts |
| --heap | Collect only cumulative allocations, allocation count, Heap peak, and post-GC usage |
| --format text|json | Select a human- or machine-readable report; default: text |
| --output <path> | Write the report to a file instead of stderr |
| --limit NAME=VALUE | Override Runtime resource limits, as with run |
| --dry-run | Block external effects, as with run, and profile plan execution |
HHY profile: examples/09-profile-algorithms.hhy
Summary
Engine bytecode
Wall time 0.013 s
CPU time 0.008 s
CPU utilization 58.8%
CPU samples 4
Heap peak 1.8 MiB
Heap after GC 92.0 KiB
Allocated 1.7 MiB
Allocations 33040
CPU hotspots
CPU% Samples Calls Function
75.0% 3 21891 fibonacci examples/09-profile-algorithms.hhy:5:1
25.0% 1 1 print examples/09-profile-algorithms.hhy:18:6
0.0% 0 1 <bytecode-top-level> examples/09-profile-algorithms.hhy:1:1
0.0% 0 1 length examples/09-profile-algorithms.hhy:12:10
0.0% 0 1 to_int examples/09-profile-algorithms.hhy:17:19
Note: fewer than 10 CPU samples; use a larger workload for stable results.
Allocation hotspots
Bytes Objects Function
1.7 MiB 32856 fibonacci examples/09-profile-algorithms.hhy:5:1
11.6 KiB 184 <bytecode-top-level> examples/09-profile-algorithms.hhy:1:1
fibonacci 6765Interpreter performance evolution
v1.7.1 defaults to the Compiler/Verifier-validated Bytecode VM. Native Opcode dispatch, static slots, reusable call frames, and low-allocation closure fast paths reduce CPU cost; the AST Interpreter remains the permanent semantic oracle and explicit fallback.
From source to execution
CompilerVerifierBytecode
Optimization switches and semantic guarantees+
Six passes: folding, constant propagation, copy propagation, peephole, unreachable removal and DCE. Unsupported shapes or mismatches use the generic path. Arithmetic failures restore original-operation errors without replaying effects; repeated mismatches disable feedback.
HHY_SCALAR_REPLACEMENT=1
Separately enables local List scalar replacement, retaining GC/quota reservations without eliminating physical heap allocations.
Enable HIR / integer MIR
These are environment variables, not hhy subcommands. The commands below use macOS/Linux sh, bash or zsh; a prefix affects only that invocation. Use hhy after installation, or ./build/hhy in a source checkout. Save this file first.
fn calculate(x) { return x * 2 + 1 }
fn first(x) { return [x + 1, x * 2][0] }
for i in 0..32 {
calculate(i)
first(i)
}
print(calculate(20))
print(first(40))
# HIR only
HHY_COMPILER=ir hhy run --engine bytecode optimizer-demo.hhy
# Integer MIR only (direct compiler)
HHY_FEEDBACK_SPECIALIZATION=1 hhy run --engine bytecode optimizer-demo.hhy
# HIR + integer MIR + local List scalar replacement
HHY_COMPILER=ir HHY_FEEDBACK_SPECIALIZATION=1 HHY_SCALAR_REPLACEMENT=1 hhy run --engine bytecode optimizer-demo.hhy# HIR report goes to stderr
HHY_COMPILER=ir HHY_COMPILER_REPORT=1 hhy bytecode --metrics optimizer-demo.hhy
# Runtime hits and deoptimizations go to profile.json
HHY_COMPILER=ir HHY_FEEDBACK_SPECIALIZATION=1 HHY_SCALAR_REPLACEMENT=1 hhy profile --engine bytecode --heap --format json --output profile.json optimizer-demo.hhyFor HIR, the stderr report has compiler=structured-ir; inspect passes and size_fallback. For MIR, typed_plans in Bytecode metrics counts compiled plans; typed_specialization.enabled and sites[].hits in profile.json show enablement and actual hits. scalar_reservations counts scalar reservations. On 2026-09-08, this example produced 26 hits per function and 26 scalar reservations for the List function; timings vary by host.
# Disable individual HIR passes; HIR remains enabled
HHY_COMPILER=ir HHY_COMPILER_DISABLE=fold,dce hhy run optimizer-demo.hhy
# Disable every HIR pass; HIR remains enabled
HHY_COMPILER=ir HHY_COMPILER_DISABLE=all hhy run optimizer-demo.hhy
# Restore the default compiler and disable MIR/scalar replacement (macOS/Linux)
unset HHY_COMPILER HHY_COMPILER_DISABLE HHY_COMPILER_REPORT HHY_FEEDBACK_SPECIALIZATION HHY_SCALAR_REPLACEMENT
hhy run --engine bytecode optimizer-demo.hhyIn Windows PowerShell, use this environment-variable syntax; remove the variables afterward to restore defaults.
$env:HHY_COMPILER="ir"
$env:HHY_FEEDBACK_SPECIALIZATION="1"
$env:HHY_SCALAR_REPLACEMENT="1"
hhy run --engine bytecode optimizer-demo.hhy
Remove-Item Env:HHY_COMPILER, Env:HHY_FEEDBACK_SPECIALIZATION, Env:HHY_SCALAR_REPLACEMENTRuntime resource limits
The run command accepts repeatable --limit NAME=VALUE options. Sizes require b/kb/mb/gb/kib/mib/gib, durations require ns/us/ms/s/min/h, and counts have no unit.
hhy run --limit max_runtime=30s --limit max_memory=256mib script.hhy| Limit | Default |
|---|---|
| max_memory | 512mib |
| max_open_files | 256 |
| max_processes | 16 |
| max_parallelism | 16 |
| max_http_body | 16mib |
| max_regex_steps | 1000000 |
| max_recursion | 256 |
| max_runtime | 0 (no total CLI limit) |
Stable exit codes
0 success
1 unhandled runtime error
2 syntax or static-check error
3 invalid CLI usage
4 file I/O, process, or network error
5 timeout or cancellationAutomation should branch on stable exit codes rather than error text.