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.
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. Starting the server
start is the primary serve command. A bare invocation with no subcommand serves identically,
so these are equivalent:
ipmideck start
# or, with no subcommand:
ipmideck
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:
ipmideck start --host 127.0.0.1 --port 8080
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. |
serve is a deprecated alias of start — prefer start (or a bare ipmideck) in new
scripts.
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:
- An explicit
--host / --port flag on the command line.
- Configuration — which itself resolves env var (
IPMIDECK_SERVER_HOST / IPMIDECK_SERVER_PORT)
over config.yaml over the built-in default.
- 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.
The IPMIDECK_SERVER_HOST and IPMIDECK_SERVER_PORT environment variables use the
IPMIDECK_ prefix. See Configuration for the full list of overrides. 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:
It writes a cert + key pair under data/certs/, records their paths into the server block of
config.yaml, and prints three lines:
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.
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:
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:
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.
--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.
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). |
--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