mkcert-cli

1.5.0 verified Mon Apr 27 auth: no javascript

mkcert-cli is a Node.js CLI wrapper around the mkcert tool for generating locally trusted HTTPS development certificates, usable outside Vite contexts. Current stable version is 1.5.0, released Apr 2024. It insources logic from vite-plugin-mkcert, removing external dependencies like axios (since v1.4.0) to keep the package small (~20 kB install size). It supports custom output directories, certificate file names, and multiple hostnames, with auto-upgrade of the mkcert binary via the `-u` flag. Compared to using mkcert directly, it simplifies certificate generation via a single npx command without requiring manual installation of the mkcert binary.

Common errors

error Error: spawn mkcert ENOENT ↓

cause The mkcert binary is not installed or not on PATH.

fix

Run with -u flag to auto-download mkcert: npx mkcert-cli -u

error Error: read ECONNRESET ↓

cause Network issue when downloading mkcert binary (e.g., behind proxy).

fix

Install mkcert manually from https://github.com/FiloSottile/mkcert and ensure it's on PATH.

error Error: EACCES: permission denied, open '/root/.mkcert-cli/certs/dev.key' ↓

cause Running as root with restrictive file permissions.

fix

Use a custom output directory with write permissions: npx mkcert-cli --outDir /tmp/certs

Warnings

gotcha The CLI generates certificates only for localhost and local IP addresses by default; custom hosts must be passed via multiple `--host` arguments. ↓

fix Use `--host host1 --host host2` syntax; prior versions had a bug ignoring custom hosts.

deprecated The `--hosts` option was renamed to `--host` in v1.5.0; `--hosts` is still accepted but may be removed in a future release. ↓

fix Use `--host` instead of `--hosts`.

gotcha The package requires Node.js >=12.20, but mkcert binary may not be available for all platforms (e.g., ARM64 Linux). The `-u` flag downloads the latest mkcert binary, which may fail behind a proxy or in restricted networks. ↓

fix Ensure mkcert is available on PATH or use `-u` in an unrestricted network.

gotcha Certificates are regenerated only if they don't exist or when `-f` is passed; overwriting existing certs requires explicit `-f` flag. ↓

fix Use `mkcert-cli -f` to force regeneration.

Install

npm install mkcert-cli

yarn add mkcert-cli

pnpm add mkcert-cli

Imports

mkcert-cli (CLI invocation)
wrong
```
npm i -g mkcert-cli && mkcert-cli
```
correct
```
npx mkcert-cli
```
Use npx to avoid global install; CLI is the only interface.

Quickstart

Generates locally trusted HTTPS certificates for custom hosts in a specified output directory with custom file names.

npx -y mkcert-cli --outDir ./certs --cert localhost.pem --key localhost.key --host localhost --host my-site.local