CLI

The shutdown-check CLI has two commands. init creates a starter config. test starts your service and verifies its behavior after SIGTERM.

Install and open the help

npm install -D shutdown-check
npx shutdown-check --help

The installed help output is:

shutdown-check — verify graceful shutdown with a real in-flight HTTP request
 
Usage:
  shutdown-check init [--config FILE]
  shutdown-check test [--config FILE] [--json] [--junit FILE]
  shutdown-check --help
  shutdown-check --version
 
Default config: shutdown-check.json
Exit codes: 0 passed, 1 shutdown check failed, 2 setup/configuration error

Running shutdown-check without arguments also prints the help.

Commands

Create a config with init

npx shutdown-check init

init writes shutdown-check.json in the current directory.

Use --config to choose another path:

npx shutdown-check init --config config/shutdown-check.json

The command prints the created path and reminds you to edit the command, port, and routes. It never overwrites a file. If the target exists, the CLI exits with code 2:

shutdown-check: EEXIST: file already exists, open '/home/me/my-service/shutdown-check.json'

Edit the existing file, rename it, or choose a different --config path. The configuration reference explains every generated field.

Run a check with test

npx shutdown-check test

test reads the config, starts the command, waits for readiness, creates active work, sends SIGTERM, and checks the response and process exit.

Common forms:

npx shutdown-check test
npx shutdown-check test --config config/shutdown-check.json
npx shutdown-check test --json
npx shutdown-check test --junit shutdown-result.xml
npx shutdown-check test --json --junit shutdown-result.xml

--config FILE

Read a config from another path. Relative paths are resolved from the current working directory. Inside the file, cwd is resolved from the config file's folder.

--json

Replace the readable text output on stdout with the complete JSON result. This is useful for scripts and structured CI logs. It does not change the process exit code.

--junit FILE

Write a JUnit XML report in addition to text or JSON output. The parent folder must already exist. The file is written before the normal result is printed.

--json and --junit belong to test. Passing either to init is an unknown option.

Help and version flags

npx shutdown-check --version

How is the config path resolved?

Without --config, the CLI reads shutdown-check.json from the directory where you run the command.

With this layout:

my-service/
├── config/
│   └── shutdown-check.json
└── dist/
    └── server.js

run:

npx shutdown-check test --config config/shutdown-check.json

Then use "cwd": ".." inside the config if the server command should run from my-service/.

The CLI accepts JSON only. For a TypeScript config, use defineConfig() and checkShutdown() from the Node API.

Text output

The default output contains:

1. PASS or FAIL, followed by a diagnostic code and message;
2. a timeline with milliseconds since the run began;
3. on failure, the last 8 KiB of service stderr and stdout when present.

FAIL SC101: Service exited before becoming ready: code 1
 
Timeline:
  +    7 ms  process launched — pid=74471
  +   47 ms  process exited — code=1, signal=none
  +  111 ms  check failed — SC101: Service exited before becoming ready: code 1
 
Service stderr (last 8 KiB):
Error: Cannot find module ./dist/server.js

Start with the code, then read the final successful timeline event. The diagnostic code pages give a cause and fix for each failure.

Errors before the test begins

Command-line and config errors start with shutdown-check:. They have no SC code or timeline because the test did not run.

See troubleshooting for configuration, startup, and shutdown failures grouped by symptom.

Exit codes

• 0 means the configured shutdown contract passed.
• 1 means the check ran and returned a failing SC code.
• 2 means invalid arguments, configuration, or setup stopped the check.

A code 1 run can still write JSON and JUnit. A code 2 run has no test result, so it writes no JUnit report.

Other package managers

Each command runs the version installed in the current project.

Related

• Quick start
• Configuration reference
• Output and reports
• Run in CI
• Troubleshooting