@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