CLI commands
Everything is done through one binary, miraserve. This page lists each command, its subcommands and the flags you will use most, with one example each. For the full list, run miraserve <command> --help.
| Command | What it does |
|---|---|
run | Starts the server. |
check | Validates a config file against the schema and security rules. |
reload | Asks a running server to load its config again without dropping connections. |
cert | Inspects certificates and generates development certificates. |
version | Prints the version, build target and security defaults. |
import | Converts an Nginx, Apache, Caddy or OpenLiteSpeed config to a draft MiraServe config. |
publish | Signs, deploys, lists and rolls back versioned site releases. |
keyd | Runs the separate process that holds TLS private keys. |
service | Generates service files for systemd, launchd or Windows. |
Every command accepts -h/--help and -V/--version. If you do not give run or check a config file, they use miraserve.kdl in the current directory.
run
miraserve run [OPTIONS] [CONFIG] starts the server with HTTP/1.1, HTTP/2 and HTTP/3 over TLS 1.3. It runs until it receives SIGINT or SIGTERM, then lets open connections finish. On Unix, SIGHUP reloads the config.
| Flag | Meaning |
|---|---|
--dev-tls | Generates a self-signed ECDSA P-256 certificate in memory when no certificate, ACME block or key daemon is configured. For local testing only. |
--acme-dir <ACME_DIR> | Directory for the ACME account and issued certificates. |
--pid-file <PID_FILE> | Writes the process ID on startup and removes the file on clean shutdown. reload uses it. |
--log-level <LOG_LEVEL> | Log filter, such as info, debug or a RUST_LOG expression. Default info. |
--log-file <LOG_FILE> | Appends logs to a file, for setups where standard output is not kept. |
--keyd-auth-secret-file <FILE> | Shared secret for talking to keyd over loopback TCP. |
--no-sandbox | Skips Landlock and seccomp at startup. For debugging only. |
$ miraserve run /etc/miraserve/conf/miraserve.kdl --acme-dir /var/lib/miraserve/acme --pid-file /run/miraserve/miraserve.pid
check
miraserve check [OPTIONS] [CONFIG] parses the config, rejects unknown or mistyped settings, and warns about choices that weaken security. Pass - to read from standard input. Run it before every start and reload, and in CI.
| Flag | Meaning |
|---|---|
--strict | Exits with status 1 if there is any security warning. |
--fs | Also checks that the files and folders the config points to exist and can be read: certificates, keys, CA bundles, site roots, WASM modules, bot-auth key files and publish keys. |
--dev-tls | Says the server will be started with --dev-tls, so the missing-certificate warning W015 is not raised. |
--format <FORMAT> | text (default) or json. |
--dump-normalized | Includes the full config with all defaults filled in. |
-q, --quiet | Hides the success line. Errors and warnings are still shown. |
$ miraserve check --strict --fs /etc/miraserve/conf/miraserve.kdl
OK: '/etc/miraserve/conf/miraserve.kdl' is valid (2 listener(s), 1 site(s), 0 route(s), TLS >= 1.3, PQC: X25519MLKEM768 enabled, 0 warning(s))
reload
miraserve reload [OPTIONS] sends SIGHUP to a running server, which loads the new config without dropping open connections. If you pass --config, the file is validated first, and nothing is sent if it fails.
| Flag | Meaning |
|---|---|
--pid-file <PID_FILE> | PID file of the running server. Default miraserve.pid. |
--config <CONFIG> | Config file to validate before signalling. |
$ sudo miraserve reload --pid-file /run/miraserve/miraserve.pid --config /etc/miraserve/conf/miraserve.kdl
cert
miraserve cert <COMMAND> works with certificates without OpenSSL.
| Subcommand | What it does | Useful flags |
|---|---|---|
inspect <CERT_PEM> | Prints the subject, issuer, SANs (the names a certificate covers) and validity dates of a PEM certificate chain. | --format text|json |
generate-dev | Writes a self-signed ECDSA P-256 certificate and key for development. localhost, 127.0.0.1 and ::1 are always included. | --hosts, --cert (default dev-cert.pem), --key (default dev-key.pem), --force |
ech-generate | Meant to generate an Encrypted Client Hello config and DNS record. It currently refuses to run, because the server cannot yet decrypt ECH. | --public-name, --rotate-secs, --format |
$ miraserve cert generate-dev --hosts localhost,dev.example.test
OK: generated self-signed ECDSA P-256 dev certificate 'dev-cert.pem' and key 'dev-key.pem'
$ miraserve cert inspect dev-cert.pem
Certificate: dev-cert.pem
Subject: CN=MiraServe Dev Certificate, O=MiraServe Local Dev
Issuer: CN=MiraServe Dev Certificate, O=MiraServe Local Dev
SANs: localhost, dev.example.test, 127.0.0.1, ::1
Existing files are not replaced unless you add --force.
version
miraserve version prints the version, the platform it was built for, and the security defaults compiled in. It takes no flags. miraserve --version prints only the version line.
$ miraserve version
miraserve 0.1.0-alpha.0
platform: aarch64-macos
defaults: TLS 1.3 only, X25519MLKEM768 PQC hybrid, H3/H2/H1, dual-stack IPv4+IPv6, cap-std, forbid(unsafe_code)
import
miraserve import [OPTIONS] <INPUT> converts a config from another server into a draft MiraServe config. Pass - to read from standard input. If it finds a security control it cannot translate, it exits non-zero and writes nothing. The output is a draft. Read Migrating before you use it.
| Flag | Meaning |
|---|---|
--from <FROM> | auto (default), nginx, caddy, apache or openlitespeed. |
-o, --output <FILE> | Writes the config to a file instead of standard output. |
--force | Allows --output to replace an existing file. |
--format <FORMAT> | kdl (default; config on standard output, notes on standard error) or json (full report). |
--allow-insecure | Writes the draft and exits 0 even when security controls could not be translated. For offline review only. Never deploy the result as it is. |
$ miraserve import /etc/nginx/sites-enabled/example.conf --from nginx --output example.kdl
publish
miraserve publish <COMMAND> manages signed, versioned releases of a static site. A release is checked (for example for leaked secrets and size), stored as an unchangeable version, and switched in atomically. You can roll back to an earlier one. See Publishing.
| Subcommand | What it does | Useful flags |
|---|---|---|
keygen | Creates an Ed25519 key pair. The secret key file gets mode 0600 on Unix. | --secret (default publisher.key), --public (default publisher.pub), --force |
sign <SITE_DIR> | Packs and signs a folder into a JSON bundle. | --key, -o/--output, --site-id, --note, --force |
verify <BUNDLE_JSON> | Checks a bundle's signature. | --pubkey |
deploy <SITE_DIR> | Runs the pre-flight checks and publishes a folder as a new release. | --config, --site, --key, --pubkey, --note, --no-inline-scripts, --format |
rollback | Switches back to the previous release, or to --release-id. | --config, --site, --storage, --release-id, --pubkey |
list | Lists stored releases and marks the active one. | --storage (required), --format |
resign | Signs stored releases again with a new key, for key rotation. | --key (required), --config, --site, --old-pubkey, --release-id |
deploy requires --config so that the site's signing and pre-flight rules from the config are applied. Add --site when the config has more than one publishing site. Deploying without a config needs --allow-unconfigured-policy and --storage, and is meant for development only. A config with a publishing site:
server {
listen ":443" protocols="h3,h2,h1"
tls {
acme {
email "[email protected]"
challenge "tls-alpn-01"
}
}
}
site "www.example.com" {
ai-publish {
storage "/var/lib/miraserve/releases/www"
site-id "www.example.com"
keep-versions 10
require-signature "ed25519:/etc/miraserve/deploy.pub"
preflight-checks "no-secrets" "max-size=50MB"
}
}
$ miraserve publish keygen --secret deploy.key --public deploy.pub
OK: generated Ed25519 publishing key pair (public: 'deploy.pub', secret: 'deploy.key')
$ miraserve publish deploy ./public --config /etc/miraserve/conf/miraserve.kdl --site www.example.com --key deploy.key --note "first release"
OK: published release rel-1795106138-0001-ac56bb62 (1 file(s), 60 bytes, signed=true, sha256=ac56bb62…)
$ miraserve publish list --storage /var/lib/miraserve/releases/www
* rel-1795106138-0001-ac56bb62 files=1 bytes=60 signed=true note=first release
keyd
miraserve keyd [OPTIONS] runs the key daemon: a separate process that holds the TLS private keys and only signs on request. The server process that faces the internet then never has the keys in its memory. Pair it with key-isolation "split-daemon" and keyd-socket in the server's tls block. See TLS and certificates and Deployment.
| Flag | Meaning |
|---|---|
--socket <SOCKET> | Unix socket path, or tcp://127.0.0.1:<port>. Default /run/miraserve-keyd/keyd.sock. |
--config <CONFIG> | Loads the certificate and key pairs named in a MiraServe config. |
--cert, --key, --hosts | Loads one certificate and key directly, for the given SNI host names. |
--allow-peer-user <USER_OR_UID> | Lets exactly this Unix user (normally miraserve) use the socket. The kernel checks the caller's user ID. |
--auth-secret-file <FILE> | 32-byte shared secret for loopback TCP mode. |
--allow-tls12 | Allows TLS 1.2 signing for all keys. By default only keys of sites that enable TLS 1.2 can sign TLS 1.2 handshakes. |
--dev-tls | Generates a temporary development certificate inside keyd. |
$ sudo -u miraserve-keyd miraserve keyd --config /etc/miraserve/conf/miraserve.kdl --allow-peer-user miraserve
The matching server config:
server {
listen ":443" protocols="h3,h2,h1"
tls {
key-isolation "split-daemon"
keyd-socket "/run/miraserve-keyd/keyd.sock"
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/keys/example.com.key"
}
}
site "example.com" {
root "/var/www/example"
}
service
miraserve service generate --target <TARGET> writes a hardened service definition. Without --output it prints to standard output.
| Target | Produces |
|---|---|
systemd | miraserve.service for the server, running as the unprivileged miraserve user with only CAP_NET_BIND_SERVICE. |
systemd-keyd | miraserve-keyd.service for the key daemon, running as miraserve-keyd. |
launchd | A macOS LaunchDaemon property list, app.miraserve.server.plist. |
windows | A PowerShell installer, install-miraserve-service.ps1, that registers a boot-time Scheduled Task. This is not a native Windows service. Treat it as a development setup. |
| Flag | Meaning |
|---|---|
--binary, --config, --acme-dir | Paths written into the unit. |
--user, --group | Service account. Defaults depend on the target. |
--split-keyd | Makes the server unit want miraserve-keyd.service. |
--no-wasm | Adds MemoryDenyWriteExecute=yes when you do not use WebAssembly plugins. |
--graceful-drain <SECONDS> | Used to compute the stop timeout. It is read from the config when that file exists. Otherwise the default is 30. |
-o, --output <FILE>, --force | Writes to a file, and replaces an existing file only with --force. |
$ sudo miraserve service generate --target systemd --no-wasm --output /etc/systemd/system/miraserve.service
$ sudo systemctl daemon-reload
The generated systemd unit runs miraserve check --fs before it starts the server, and uses miraserve reload for systemctl reload.