# hulla CLI reference

> Look up implemented hulla CLI commands, flags, config fields, and their exact defaults.

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.

## Commands and aliases

| 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.

> **Warning: Nested help is not a dry run**
>
> Root `hulla --help` prints `Help output is not implemented yet.` Nested `--help` can continue into normal command behavior. Don't use it to preview file changes.

`--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.

## Project config fields

`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.

## UI config fields

`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:

```json
{
  "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](https://hulla.dev/docs/cli/ui.md#update-and-remove-deliberately) to refresh them without clearing unrelated cache entries.

## Exit and error behavior

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](https://hulla.dev/docs/cli/automation.md) for a repeatable add command.