> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ipmideck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Run ipmideck from the command line: subcommands, bind flags, the 0.0.0.0:3000 default, self-signed HTTPS, demo mode, and exit codes.

ipmideck ships a single console command, `ipmideck`, that starts the server, resets the
admin password, or generates a self-signed certificate. `ipmilink` is a backward-compatible
alias for the same command, every subcommand and flag below works identically under either
name.

<Note>
  The CLI only applies when you run ipmideck directly (pip install or a source checkout). The
  Docker image launches `uvicorn backend.main:app` directly and never invokes the CLI, so none
  of these flags, the bind precedence, or the single-instance guard apply to the container. The container's bind is set by its own startup command. See [Installation](/en/installation).
</Note>

## Starting the server

`start` is the primary serve command. A bare invocation with no subcommand serves identically,
so these are equivalent:

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck start
  # or, with no subcommand:
  ipmideck
  ```

  ```cmd cmd theme={null}
  ipmideck start
  :: or, with no subcommand:
  ipmideck
  ```

  ```bash bash theme={null}
  ipmideck start
  # or, with no subcommand:
  ipmideck
  ```
</CodeGroup>

With no flags, ipmideck binds **`0.0.0.0:3000`** by default, reachable on every interface,
on port `3000`. Open `http://<your-ip>:3000` once it is up.

Override the bind with `--host` and `--port`:

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck start --host 127.0.0.1 --port 8080
  ```

  ```cmd cmd theme={null}
  ipmideck start --host 127.0.0.1 --port 8080
  ```

  ```bash bash theme={null}
  ipmideck start --host 127.0.0.1 --port 8080
  ```
</CodeGroup>

## Subcommands

| Subcommand       | What it does                                                                             |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `start`          | Start the server (default). A bare `ipmideck` with no subcommand also serves.            |
| `serve`          | Deprecated alias of `start`. Behaves identically; kept so existing scripts keep working. |
| `reset-password` | Interactively create or update the admin login, then exit without serving.               |

<Note>
  `serve` is a deprecated alias of `start`, prefer `start` (or a bare `ipmideck`) in new
  scripts.
</Note>

## Flags

These top-level flags apply to the serve path. `--demo` and `--config` are read before any
subcommand branch, so they also affect `reset-password` and `--gen-cert`.

| Flag              | Effect                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `--host <host>`   | Bind host. Default comes from `config.yaml` or `0.0.0.0`. An explicit flag wins over config.       |
| `--port <port>`   | Bind port. Default comes from `config.yaml` or `3000`. An explicit flag wins over config.          |
| `--demo`          | Run in demo mode with simulated data.                                                              |
| `--config <path>` | Path to a `config.yaml` to load.                                                                   |
| `--reload`        | Enable auto-reload for development.                                                                |
| `--gen-cert`      | Generate a self-signed cert + key under `data/certs/`, write the paths to `config.yaml`, and exit. |

## Bind precedence

The host and port ipmideck actually binds are resolved in this order, highest priority first:

1. An explicit `--host` / `--port` flag on the command line.
2. Configuration, which itself resolves env var (`IPMIDECK_SERVER_HOST` / `IPMIDECK_SERVER_PORT`)
   over `config.yaml` over the built-in default.
3. The hardcoded fallback **`0.0.0.0:3000`**, used if the early config load fails.

In other words: a value you persist to `config.yaml` is **overridden by an `IPMIDECK_`
environment variable or a `--host` / `--port` flag** on the next boot, env and CLI always win.
If `config.yaml` is malformed, ipmideck prints a warning to stderr and falls back to
`0.0.0.0:3000`.

<Note>
  The `IPMIDECK_SERVER_HOST` and `IPMIDECK_SERVER_PORT` environment variables use the
  `IPMIDECK_` prefix. See [Configuration](/en/configuration) for the full list of overrides.
</Note>

## HTTPS with --gen-cert

`--gen-cert` generates a self-signed certificate and key, then exits. It does **not** start
the server and does **not** turn HTTPS on by itself:

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck --gen-cert
  ```

  ```cmd cmd theme={null}
  ipmideck --gen-cert
  ```

  ```bash bash theme={null}
  ipmideck --gen-cert
  ```
</CodeGroup>

It writes a cert + key pair under `data/certs/`, records their paths into the `server` block of
`config.yaml`, and prints three lines:

```text theme={null}
Generated: <path-to-cert>
Generated: <path-to-key>
Wrote cert_file/key_file to config.yaml. Set server.https=true and restart to serve over HTTPS.
```

To actually serve over HTTPS, set `server.https: true` in `config.yaml` and restart ipmideck. HTTPS is never enabled automatically.

## Demo mode

`--demo` runs ipmideck against simulated hardware instead of real BMCs, useful for evaluating
the dashboard without any servers wired up:

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck start --demo
  ```

  ```cmd cmd theme={null}
  ipmideck start --demo
  ```

  ```bash bash theme={null}
  ipmideck start --demo
  ```
</CodeGroup>

Demo mode is set very early, before any subcommand branch, so the whole app (config and the running server) sees it.

## Resetting the admin password

`reset-password` interactively creates or updates the admin login, then exits without ever
starting the server:

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck reset-password
  ```

  ```cmd cmd theme={null}
  ipmideck reset-password
  ```

  ```bash bash theme={null}
  ipmideck reset-password
  ```
</CodeGroup>

It prompts for `Username:` and then `New password:` (hidden input). If an account already
exists, it updates that user's password and prints `Password updated for <username>`; otherwise
it creates the user and prints `User <username> created`.

## Development auto-reload

`--reload` is a development-only fast path: it hands off to uvicorn's own auto-reloading
supervisor and returns. It intentionally **skips the single-instance port guard** described
below, because the reloader runs its own supervisor process.

<CodeGroup>
  ```powershell PowerShell theme={null}
  ipmideck start --reload
  ```

  ```cmd cmd theme={null}
  ipmideck start --reload
  ```

  ```bash bash theme={null}
  ipmideck start --reload
  ```
</CodeGroup>

<Warning>
  `--reload` is for development only. Because it bypasses the single-instance guard, run it on a
  host where no other ipmideck instance is already bound to the same port.
</Warning>

## Exit codes

| Exit code | When                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `0`       | Clean shutdown on `Ctrl+C` / SIGTERM, the server stops gracefully, no traceback.                                                                                                                                                |
| `1`       | The port is already in use on the target host (another instance may be running), **or** the bind fails because the address is unavailable or not permitted (for example a privileged port or an interface that does not exist). |

On the serve path (not `--reload`), ipmideck runs a single-instance guard before binding. If the
port is already in use it prints an error to stderr and exits `1`. If the bind fails because the
address is unavailable or not permitted, it prints a distinct error and also exits `1`.

## Next steps

* [Configuration](/en/configuration): `config.yaml` keys and the `IPMIDECK_` environment overrides.
* [Installation](/en/installation): install ipmideck with Docker or pip.
* [Troubleshooting](/en/troubleshooting): connection, port, and IPMI errors.