Reference / CLI commands

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.

CommandWhat it does
runStarts the server.
checkValidates a config file against the schema and security rules.
reloadAsks a running server to load its config again without dropping connections.
certInspects certificates and generates development certificates.
versionPrints the version, build target and security defaults.
importConverts an Nginx, Apache, Caddy or OpenLiteSpeed config to a draft MiraServe config.
publishSigns, deploys, lists and rolls back versioned site releases.
keydRuns the separate process that holds TLS private keys.
serviceGenerates 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.

FlagMeaning
--dev-tlsGenerates 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-sandboxSkips 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.

FlagMeaning
--strictExits with status 1 if there is any security warning.
--fsAlso 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-tlsSays the server will be started with --dev-tls, so the missing-certificate warning W015 is not raised.
--format <FORMAT>text (default) or json.
--dump-normalizedIncludes the full config with all defaults filled in.
-q, --quietHides 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.

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

SubcommandWhat it doesUseful 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-devWrites 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-generateMeant 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.

FlagMeaning
--from <FROM>auto (default), nginx, caddy, apache or openlitespeed.
-o, --output <FILE>Writes the config to a file instead of standard output.
--forceAllows --output to replace an existing file.
--format <FORMAT>kdl (default; config on standard output, notes on standard error) or json (full report).
--allow-insecureWrites 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.

SubcommandWhat it doesUseful flags
keygenCreates 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
rollbackSwitches back to the previous release, or to --release-id.--config, --site, --storage, --release-id, --pubkey
listLists stored releases and marks the active one.--storage (required), --format
resignSigns 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.

FlagMeaning
--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, --hostsLoads 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-tls12Allows 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-tlsGenerates 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.

TargetProduces
systemdmiraserve.service for the server, running as the unprivileged miraserve user with only CAP_NET_BIND_SERVICE.
systemd-keydmiraserve-keyd.service for the key daemon, running as miraserve-keyd.
launchdA macOS LaunchDaemon property list, app.miraserve.server.plist.
windowsA 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.
FlagMeaning
--binary, --config, --acme-dirPaths written into the unit.
--user, --groupService account. Defaults depend on the target.
--split-keydMakes the server unit want miraserve-keyd.service.
--no-wasmAdds 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>, --forceWrites 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.