# Global Flags & Exit Codes

Flags may appear anywhere in the invocation — before the command, after the config path, interleaved. `sovrium --watch start app.yaml` and `sovrium start app.yaml --watch` are the same command.

## Flags

| Flag                 | Commands         | Description                                                                       |
| -------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `--watch`, `-w`      | `start`          | Watch the config file and hot-reload on change.                                   |
| `--publicDir <path>` | `start`, `build` | Static-asset directory to serve (or copy into the build output).                  |
| `--no-publicDir`     | `start`, `build` | Serve no static assets. Overrides both the env var and the default.               |
| `--output <path>`    | `schema`         | Write the JSON Schema to a file instead of stdout.                                |
| `--template <name>`  | `init`           | Bundled template name, or a GitHub repo (`owner/repo[#ref]`).                     |
| `--name <name>`      | `init`           | App name written into the scaffolded config.                                      |
| `--force`            | `init`           | Overwrite an existing `app.yaml`.                                                 |
| `--config <path>`    | `admin create`   | Config used to resolve the auth settings.                                         |
| `--password <value>` | `admin create`   | Admin password. Omit it to be prompted, which requires a TTY.                     |
| `--message <text>`   | `reload`         | Operator note recorded against the new configuration version.                     |
| `--version`, `-v`    | any              | Print the version and exit. Always wins, wherever it appears.                     |
| `--help`, `-h`       | any              | Print help and exit. With a command in front, prints that command's help instead. |

## Static Assets

`--publicDir` is the one flag with a three-step fallback, shared by `start` and `build`:

1. `--no-publicDir` — opt out entirely; nothing else is consulted.
2. `--publicDir <path>` — the explicit path.
3. `SOVRIUM_PUBLIC_DIR` — the same thing from the environment. The literal value `none` is the env-var spelling of `--no-publicDir`.
4. Otherwise, `public/` **next to the config file**.

The default is anchored to the config file rather than to the working directory on purpose: the same command serves the same files no matter where you run it from. With an inline `APP_SCHEMA` there is no config file to anchor to, so no default applies.

```bash
sovrium start app.yaml --publicDir ./assets
sovrium start app.yaml --no-publicDir
SOVRIUM_PUBLIC_DIR=none sovrium build app.yaml
```

## Unknown Flags Are Rejected

Any `-`-prefixed token that is not in the table above stops the command before it dispatches:

```text
Error: Unknown flag "--wtach"
```

This exists because of what used to happen instead. A typo'd flag was treated as a positional argument, fell through to the implicit `start`, and failed with `Error: No configuration provided` — an accurate message about entirely the wrong problem. Now the offending token is named.

## Exit Codes

| Code | Meaning                                                                         |
| ---- | ------------------------------------------------------------------------------- |
| `0`  | Success                                                                         |
| `1`  | Failure — invalid config, missing file, unknown command or flag, refused action |

Every failure path exits `1`; the distinction lives in the message, not the code. That makes CI gating a one-liner:

```bash
sovrium validate app.yaml || exit 1
```

An unhandled failure prints an `Unexpected error:` banner with a link to open an issue. That banner means Sovrium itself did not anticipate the failure — worth reporting, with the message copied in.

## Related Pages

- [CLI Overview](/en/docs/cli) — commands and configuration sources.
- [Project Commands](/en/docs/cli-project) — the commands most of these flags belong to.
- [Environment Variables](/en/docs/env-vars) — the env-var half of the CLI's inputs.