Reference
hulla CLI reference
Look up implemented hulla CLI commands, flags, config fields, and their exact defaults.
On this page
Look up commands, flags, and configuration defaults for hulla beta 0.0.0-beta.1. The npm package is named hulla, and its executable requires Bun.
| Command | Alias | Behavior |
|---|---|---|
hulla init | hulla initialize | Detects project package scripts and writes .hulla/hulla.json; --clean is accepted by the parser but currently has no separate behavior. |
hulla ui init | hulla ui i | Interactively configures registry sources, framework install destinations, support files, dependencies, class composer, and optional post-add formatter. |
hulla ui add <components…> | hulla ui a | Copies named component source files from the configured registry. Existing copied files may be updated. |
hulla ui remove <components…> | hulla ui r | Requests confirmation before removing each named component directory. |
hulla api init | — | Legacy generator initializer; output targets an older @hulla/api API. |
hulla api generate | — | Loads and runs the legacy generator config. Not compatible with @hulla/api 2.0. |
hulla api dev | — | Watches legacy generator inputs and regenerates; not compatible with @hulla/api 2.0. |
hulla install | hulla i, hulla add | Currently checks that the selected directory exists and reports success; it does not install packages yet. |
The root command accepts --version, --help, --yes/-y, and --config <path> before a command. hulla --version prints the installed version.
--yes accepts confirmations but doesn’t choose missing names or frameworks. Root --config <path> selects a project config for commands that load one; hulla install --config <directory> instead checks a directory.
| Invocation | Declared arguments and behavior |
|---|---|
hulla | --version, --help, --yes/-y, --config <path> |
hulla init | --config, --help, --yes/-y, --clean; --clean is parsed but has no separate effect. |
hulla install | --help, --yes, --config, optional package-name tokens; currently only checks the selected directory. |
hulla ui | --help, --yes, --config, --framework; place --framework here before remove. |
hulla ui init | --help, --yes, --config. |
hulla ui add <components…> | --help, --yes, --config, --framework; requires one or more component names. |
hulla ui remove <components…> | --help, --yes, --config; requires one or more component names. |
hulla api and hulla api init/generate/dev | Each declares --help, --yes, and --config; the API runner reads its command-level config value. |
Put root --config <absolute-path> before ui to select a different project config. Nested UI config fields don’t select it.
--framework <name> chooses between installed targets. Only yes has a short alias (-y); help, version, and config don’t. The root parser supports grouped single-character short flags through sharedDash. hulla ui add --yes without component names returns an error.
hulla init writes .hulla/hulla.json; the schema also fills omitted optional defaults when loading it.
| Field | Required in file | Default or purpose |
|---|---|---|
cli.scripts.add | Yes | Package install command, e.g. bun add. |
cli.scripts.addDev | Yes | Development dependency command, e.g. bun add -D. |
cli.scripts.uninstall | Yes | Removal command, e.g. bun remove. |
cli.scripts.upgrade | Yes | Update command, e.g. bun update. |
cli.cache | No | Defaults to true; accepted in config but currently does not enable or disable cache reads/writes. |
cli.cacheDir | No | Defaults to <current-working-directory>/.hulla/.cache; used for the UI source cache file. |
cli.logs | No | Defaults to true; accepted in config but currently does not change logging behavior. |
configs.api | No | api.config.ts. |
configs.ui | No | .hulla/ui.json. |
$schema | No | Editor/schema URL metadata. |
--config <path> names a JSON file for commands that load project settings. Use an absolute path: the current relative-path flow can resolve the value twice.
For UI settings, the config’s directory is the project root, except that a config inside .hulla/ uses its parent. configs.ui resolves from that root.
hulla init writes .hulla/hulla.json and records detected package scripts. Loading the file fills optional fields; an omitted cli.cacheDir becomes <current-working-directory>/.hulla/.cache.
cli.cacheDir controls the location of cache data used by UI registry resolution; the UI source record file is ui.cache.json inside that directory. The cli.cache boolean is currently stored but not consulted by those cache paths. cli.logs is also stored, but its true/false value currently has no effect on logging.
configs.ui points to the UI config; by default this is .hulla/ui.json, resolved from the project root. An absent UI file loads these defaults:
{
"version": 1,
"sources": ["https://github.com/hulladev/ui/tree/master/generated"],
"installs": [],
"postAddUpdateStep": ""
}Each install record written by hulla ui init includes sourceUrl, libraryName, componentsRoot, copyFilesRoot, and frameworks. A framework record includes name, templatePath, outputPath, and tsconfigPath. Optional fields are composer ("cn" or "tailwind-merge"), codeRoot, and rootTsconfigPath. hulla ui init --yes reuses a saved composer, or selects cn for a new install. The postAddUpdateStep string can run a formatter on changed files; a custom command uses the {files} placeholder.
Sources can be HTTP(S) URLs or local paths. Relative local paths resolve from the UI project root; ~ expands to the home directory. The default remote follows master; pin a tag or commit for repeatable inputs.
There are two caches: the project record at <cli.cacheDir>/ui.cache.json, and downloaded snapshots under ~/.cache/hulla/gittar. Follow UI components to refresh them without clearing unrelated cache entries.
A successful command returns exit code 0. Parser, config, filesystem, registry, and task errors are reported to stderr and return 1. Interactive cancellation may exit with 0. The CLI prints a general issue-report footer for caught failures. It does not run the consuming application’s build or tests after copying files; run those checks in your project or CI. See Automation for a repeatable add command.