@hololabdev/hhl-cli

@hololabdev/hhl-cli

CLI for orchestrating local development across a multi-app workspace.

Install

npm install -g @hololabdev/hhl-cli

From a git checkout:

pnpm install
pnpm build
node bin/hhl.js install   # optional: register `hhl` in your shell

Shell completion (optional):

eval "$(hhl completion bash)"   # or: hhl completion zsh

Quick start

hhl
hhl discover
hhl start
hhl check
hhl tail be -f
hhl tail
hhl run
hhl env
hhl setup

Commands

Getting started

Command	Description
hhl setup	Install dependencies, copy env templates, optional MongoDB
hhl discover	Find new app folders and add them to hhl.config.json
hhl doctor	Workspace health checks (--fix to auto-repair)
hhl check	Alias for doctor
hhl fix	Run doctor --fix
hhl install	Register the hhl shell command

Development

Command	Description
hhl start	Start services (--profile, --only, --show, --grep)
hhl run <service> [script]	Run npm script (--list to show scripts)
hhl build	Build all services in profile (--only)
hhl stop [service]	Stop all services or one by id
hhl down [service]	Alias for stop
hhl restart [service]	Restart one or all (--all)
hhl status	PID table with uptime (--watch)
hhl ps	Alias for status
hhl logs [service]	Tail logs (--follow, --all, --since 5m)
hhl tail [service]	Alias for logs
hhl open [service]	Open service URL in the browser (--all)

Environment

Command	Description
hhl env check [service]	List missing required env keys
hhl env diff [service]	Compare .env keys with example file
hhl env init <service>	Interactive setup (--force to re-prompt)
hhl env set <service> <KEY> <value>	Set a single env value
hhl ssl [service]	Generate self-signed SSL certs (--all)
hhl config	Print current configuration
hhl config set workspace <path>	Set workspace root
hhl kill-port <port>	Free a port blocked by another process

CLI

Command	Description
hhl version	Show version, Node.js, install source
hhl upgrade	Update the CLI
hhl completion bash|zsh	Print shell completion script
hhl -v	Print version (shortcut)

Profiles

Profiles are defined in hhl.config.json:

Profile	Typical use
full	All apps in the workspace
device	Apps needed for on-device testing
backend	API / server apps only

Examples:

hhl
hhl discover
hhl start
hhl check
hhl fix
hhl tail be -f
hhl tail
hhl run
hhl env
hhl start
hhl start --profile backend
hhl start --show be,fe
hhl start --grep "error|warn"
hhl run be --list
hhl run be db:migrate
hhl build --profile backend
hhl restart --all
hhl logs be --since 5m

Configuration

1. Copy hhl.config.example.json → hhl.config.json.
2. Set workspaceRoot to the directory that contains your app folders.
3. Adjust apps, profiles, and optional aliases.

Each app entry should define:

• path, dev, port, url
• envFile
• envExample as a string or null
• optional build
• optional requiredEnv

To add a new app folder:

1. Create the folder under your workspace with a package.json.
2. Run hhl discover.
3. Review the generated entry under apps.
4. Adjust profiles, aliases, ports, URLs, and requiredEnv if needed.

Legacy requiredEnv at the top level is still accepted for older configs, but it is normalized into apps.<service>.requiredEnv at load time.

Interactive shortcuts:

• hhl start can prompt for a profile or a custom multi-service selection when you do not pass --profile or --only.
• hhl tail can prompt for a service or all.
• hhl tail remembers the last target you selected and offers it first next time.
• hhl open can prompt for a service when multiple targets are available.
• hhl run can prompt for both service and script.
• hhl env opens an action picker for check, diff, init, and set.
• hhl env set masks prompted values for keys like TOKEN, SECRET, PASSWORD, and API_KEY.

Runtime state and logs live under .hhl/ in the workspace root. Log files use ISO timestamps.

Set HHL_NO_UPDATE_NOTIFIER=1 to disable npm update hints.

Upgrade

hhl upgrade

Or reinstall from npm:

npm install -g @hololabdev/hhl-cli@latest